ci: publish mosaic-as appservice image (M4a, agent-comms#9)

Mirrors the gateway/web kaniko pattern: sha- pinned tag always, latest on
main, tag on releases. Enables immutable-tag swarm deploy of mosaic-as.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

.woodpecker/publish.yml

@@ -114,6 +114,31 @@ steps:
     depends_on:
       - build
 
+  build-appservice:
+    image: gcr.io/kaniko-project/executor:debug
+    environment:
+      REGISTRY_USER:
+        from_secret: gitea_username
+      REGISTRY_PASS:
+        from_secret: gitea_password
+      CI_COMMIT_BRANCH: ${CI_COMMIT_BRANCH}
+      CI_COMMIT_TAG: ${CI_COMMIT_TAG}
+      CI_COMMIT_SHA: ${CI_COMMIT_SHA}
+    commands:
+      - mkdir -p /kaniko/.docker
+      - echo "{\"auths\":{\"git.mosaicstack.dev\":{\"username\":\"$REGISTRY_USER\",\"password\":\"$REGISTRY_PASS\"}}}" > /kaniko/.docker/config.json
+      - |
+        DESTINATIONS="--destination git.mosaicstack.dev/mosaicstack/stack/appservice:sha-${CI_COMMIT_SHA:0:7}"
+        if [ "$CI_COMMIT_BRANCH" = "main" ]; then
+          DESTINATIONS="$DESTINATIONS --destination git.mosaicstack.dev/mosaicstack/stack/appservice:latest"
+        fi
+        if [ -n "$CI_COMMIT_TAG" ]; then
+          DESTINATIONS="$DESTINATIONS --destination git.mosaicstack.dev/mosaicstack/stack/appservice:$CI_COMMIT_TAG"
+        fi
+        /kaniko/executor --context . --dockerfile docker/appservice.Dockerfile $DESTINATIONS
+    depends_on:
+      - build
+
   build-web:
     image: gcr.io/kaniko-project/executor:debug
     environment:

README.md

@@ -58,6 +58,8 @@ mosaic yolo pi               # Pi in yolo mode
 
 The launcher verifies your config, checks for `SOUL.md`, injects your `AGENTS.md` standards into the runtime, and forwards all arguments.
 
+Pi launches default to a token-lean skill posture: `mosaic pi` passes `--no-skills` so Pi does not preload every global skill description into the system prompt. Use `MOSAIC_PI_SKILL_MODE=all mosaic pi` for the legacy all-skills catalog, or `MOSAIC_PI_SKILL_MODE=discover mosaic pi` to let Pi use its native settings/project skill discovery.
+
 ### TUI & Gateway
 
 ```bash

apps/appservice/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@mosaicstack/mosaic-as",
+  "version": "0.0.1",
+  "type": "module",
+  "private": true,
+  "repository": {
+    "type": "git",
+    "url": "https://git.mosaicstack.dev/mosaicstack/stack.git",
+    "directory": "apps/appservice"
+  },
+  "main": "dist/main.js",
+  "bin": {
+    "mosaic-as": "dist/main.js",
+    "mosaic-as-registration": "dist/registration-main.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "lint": "eslint src",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run --passWithNoTests",
+    "dev": "tsx watch src/main.ts"
+  },
+  "dependencies": {
+    "@mosaicstack/appservice": "workspace:*"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.8.0",
+    "vitest": "^2.0.0"
+  },
+  "files": [
+    "dist"
+  ]
+}

apps/appservice/src/__tests__/server.test.ts

@@ -0,0 +1,152 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import { AppserviceDaemon } from '../server.js';
+import type { DaemonConfig, DaemonRequest } from '../server.js';
+
+const cfg: DaemonConfig = {
+  homeserverUrl: 'https://hs.example',
+  domain: 'hs.example',
+  asToken: 'as-secret',
+  hsToken: 'hs-secret',
+  bridgeTokens: ['bridge-secret'],
+};
+
+const jsonResponse = (status: number, body: unknown): Response =>
+  new Response(JSON.stringify(body), { status, headers: { 'Content-Type': 'application/json' } });
+
+const request = (overrides: Partial<DaemonRequest>): DaemonRequest => ({
+  method: 'GET',
+  path: '/',
+  searchParams: new URLSearchParams(),
+  body: undefined,
+  ...overrides,
+});
+
+const makeDaemon = () => {
+  const fetchMock = vi.fn(async (_input: URL | string) => jsonResponse(200, { event_id: '$sent' }));
+  const daemon = new AppserviceDaemon(cfg, fetchMock as unknown as typeof fetch, () => {});
+  return { daemon, fetchMock };
+};
+
+describe('AppserviceDaemon routing', () => {
+  it('serves health unauthenticated', async () => {
+    const { daemon } = makeDaemon();
+    expect((await daemon.handle(request({ path: '/health' }))).status).toBe(200);
+  });
+
+  it('404s unknown paths', async () => {
+    const { daemon } = makeDaemon();
+    expect((await daemon.handle(request({ path: '/nope' }))).status).toBe(404);
+  });
+
+  it('transactions require the hs_token', async () => {
+    const { daemon } = makeDaemon();
+    const bad = await daemon.handle(
+      request({
+        method: 'PUT',
+        path: '/_matrix/app/v1/transactions/t1',
+        authorizationHeader: 'Bearer wrong',
+        body: { events: [] },
+      }),
+    );
+    expect(bad.status).toBe(403);
+    const ok = await daemon.handle(
+      request({
+        method: 'PUT',
+        path: '/_matrix/app/v1/transactions/t1',
+        authorizationHeader: 'Bearer hs-secret',
+        body: { events: [{ type: 'm.room.message', event_id: '$e' }] },
+      }),
+    );
+    expect(ok.status).toBe(200);
+  });
+
+  it('bridge requires a bridge token (hs/as tokens do not work)', async () => {
+    const { daemon } = makeDaemon();
+    for (const token of [undefined, 'Bearer hs-secret', 'Bearer as-secret', 'Bearer nope']) {
+      const res = await daemon.handle(
+        request({
+          method: 'POST',
+          path: '/bridge/v1/messages',
+          authorizationHeader: token,
+          body: {},
+        }),
+      );
+      expect(res.status).toBe(403);
+    }
+  });
+
+  it('bridge message sends as the agent and returns the event id', async () => {
+    const { daemon, fetchMock } = makeDaemon();
+    const res = await daemon.handle(
+      request({
+        method: 'POST',
+        path: '/bridge/v1/messages',
+        authorizationHeader: 'Bearer bridge-secret',
+        body: { room_id: '!r:hs.example', agent: 'pi0-web1', body: 'hi', thread_root: '$req' },
+      }),
+    );
+    expect(res.status).toBe(200);
+    expect(res.body.event_id).toBe('$sent');
+    const sendCall = fetchMock.mock.calls
+      .map((c) => new URL(String(c[0])))
+      .find((u) => u.pathname.includes('/send/m.room.message/'));
+    expect(sendCall).toBeDefined();
+    expect(sendCall!.searchParams.get('user_id')).toBe('@agent-pi0-web1:hs.example');
+  });
+
+  it('bridge rejects invalid payloads with 400', async () => {
+    const { daemon } = makeDaemon();
+    const res = await daemon.handle(
+      request({
+        method: 'POST',
+        path: '/bridge/v1/messages',
+        authorizationHeader: 'Bearer bridge-secret',
+        body: { room_id: 'bad', agent: 'pi0', body: 'x' },
+      }),
+    );
+    expect(res.status).toBe(400);
+  });
+
+  it('bridge typing endpoint works', async () => {
+    const { daemon, fetchMock } = makeDaemon();
+    const res = await daemon.handle(
+      request({
+        method: 'POST',
+        path: '/bridge/v1/typing',
+        authorizationHeader: 'Bearer bridge-secret',
+        body: { room_id: '!r:hs.example', agent: 'pi0-web1', typing: true },
+      }),
+    );
+    expect(res.status).toBe(200);
+    const typingCall = fetchMock.mock.calls
+      .map((c) => new URL(String(c[0])))
+      .find((u) => u.pathname.includes('/typing/'));
+    expect(typingCall).toBeDefined();
+  });
+
+  it('authenticated unknown bridge sub-paths return 405, never fall through', async () => {
+    const { daemon } = makeDaemon();
+    const res = await daemon.handle(
+      request({
+        method: 'GET',
+        path: '/bridge/v1/unknown',
+        authorizationHeader: 'Bearer bridge-secret',
+      }),
+    );
+    expect(res.status).toBe(405);
+  });
+
+  it('empty bridge token list denies everything', async () => {
+    const daemon = new AppserviceDaemon({ ...cfg, bridgeTokens: [] }, undefined, () => {});
+    const res = await daemon.handle(
+      request({
+        method: 'POST',
+        path: '/bridge/v1/typing',
+        authorizationHeader: 'Bearer bridge-secret',
+        body: {},
+      }),
+    );
+    expect(res.status).toBe(403);
+  });
+});

apps/appservice/src/config.ts

@@ -0,0 +1,23 @@
+import type { DaemonConfig } from './server.js';
+
+const required = (name: string): string => {
+  const value = process.env[name];
+  if (!value) throw new Error(`missing required env var ${name}`);
+  return value;
+};
+
+export function configFromEnv(): DaemonConfig & { port: number } {
+  return {
+    homeserverUrl: required('MOSAIC_AS_HOMESERVER_URL'),
+    domain: required('MOSAIC_AS_DOMAIN'),
+    asToken: required('MOSAIC_AS_TOKEN'),
+    hsToken: required('MOSAIC_HS_TOKEN'),
+    userPrefix: process.env.MOSAIC_AS_USER_PREFIX ?? 'agent-',
+    senderLocalpart: process.env.MOSAIC_AS_SENDER_LOCALPART ?? 'mosaic-as',
+    bridgeTokens: (process.env.MOSAIC_AS_BRIDGE_TOKENS ?? '')
+      .split(',')
+      .map((t) => t.trim())
+      .filter(Boolean),
+    port: Number(process.env.MOSAIC_AS_PORT ?? 8008),
+  };
+}

apps/appservice/src/main.ts

@@ -0,0 +1,67 @@
+import http from 'node:http';
+
+import { configFromEnv } from './config.js';
+import { AppserviceDaemon } from './server.js';
+
+const cfg = configFromEnv();
+const daemon = new AppserviceDaemon(cfg);
+
+const MAX_BODY_BYTES = 1024 * 1024;
+
+const server = http.createServer((req, res) => {
+  const chunks: Buffer[] = [];
+  let received = 0;
+  let rejected = false;
+  req.on('data', (chunk: Buffer) => {
+    received += chunk.length;
+    if (received > MAX_BODY_BYTES) {
+      rejected = true;
+      res.writeHead(413, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ errcode: 'M_TOO_LARGE', error: 'request body too large' }));
+      req.destroy();
+      return;
+    }
+    chunks.push(chunk);
+  });
+  req.on('end', () => {
+    if (rejected) return;
+    void (async () => {
+      const url = new URL(req.url ?? '/', 'http://localhost');
+      let body: unknown;
+      try {
+        const raw = Buffer.concat(chunks).toString();
+        body = raw ? JSON.parse(raw) : undefined;
+      } catch {
+        res.writeHead(400, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ errcode: 'M_NOT_JSON', error: 'invalid json' }));
+        return;
+      }
+      const result = await daemon.handle({
+        method: req.method ?? 'GET',
+        path: url.pathname,
+        searchParams: url.searchParams,
+        authorizationHeader: req.headers.authorization,
+        body,
+      });
+      res.writeHead(result.status, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify(result.body));
+    })().catch((error: unknown) => {
+      console.error('request failed:', error);
+      if (res.headersSent) {
+        res.destroy();
+        return;
+      }
+      res.writeHead(500, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ error: 'internal error' }));
+    });
+  });
+});
+
+server.listen(cfg.port, () => {
+  console.log(
+    `mosaic-as listening on :${cfg.port} (homeserver ${cfg.homeserverUrl}, domain ${cfg.domain})`,
+  );
+  if (cfg.bridgeTokens.length === 0) {
+    console.warn('WARNING: MOSAIC_AS_BRIDGE_TOKENS is empty — bridge API will deny all requests');
+  }
+});

apps/appservice/src/registration-main.ts

@@ -0,0 +1,10 @@
+import { buildRegistration, registrationToYaml } from '@mosaicstack/appservice';
+
+import { configFromEnv } from './config.js';
+
+// Prints the Synapse registration YAML (mosaic-as.yaml) for the current env.
+// Usage: MOSAIC_AS_URL=http://mosaic-as:8008 mosaic-as-registration > mosaic-as.yaml
+const cfg = configFromEnv();
+const url = process.env.MOSAIC_AS_URL;
+if (!url) throw new Error('missing required env var MOSAIC_AS_URL');
+process.stdout.write(registrationToYaml(buildRegistration(cfg, { url })));

apps/appservice/src/server.ts

@@ -0,0 +1,124 @@
+import { createHmac, randomBytes, timingSafeEqual } from 'node:crypto';
+
+import {
+  AppserviceIntent,
+  TransactionHandler,
+  validateBridgeMessage,
+  validateBridgeTyping,
+} from '@mosaicstack/appservice';
+import type { AppserviceConfig, MatrixEvent } from '@mosaicstack/appservice';
+
+export interface DaemonConfig extends AppserviceConfig {
+  /** Bearer tokens accepted on /bridge/v1/* (one per agent-comms host daemon). */
+  bridgeTokens: string[];
+}
+
+export interface DaemonRequest {
+  method: string;
+  /** URL path without query string. */
+  path: string;
+  searchParams: URLSearchParams;
+  authorizationHeader?: string;
+  body: unknown;
+}
+
+export interface DaemonResponse {
+  status: number;
+  body: Record<string, unknown>;
+}
+
+// Compare equal-length HMAC digests so neither content nor LENGTH of the
+// stored secret is observable through timing.
+const HMAC_KEY = randomBytes(32);
+const digest = (value: string): Buffer => createHmac('sha256', HMAC_KEY).update(value).digest();
+
+const safeEqual = (a: string, b: string): boolean => timingSafeEqual(digest(a), digest(b));
+
+const TXN_PATH = /^\/_matrix\/app\/v1\/transactions\/([^/]+)$/;
+
+/**
+ * HTTP-framework-agnostic request router for the mosaic-as daemon: the
+ * Application Service transactions endpoint (Synapse-facing) plus the
+ * internal bridge API v1 (agent-comms daemon-facing). main.ts binds this to
+ * node:http; tests drive it directly.
+ */
+export class AppserviceDaemon {
+  readonly intent: AppserviceIntent;
+  private readonly transactions: TransactionHandler;
+
+  constructor(
+    private readonly cfg: DaemonConfig,
+    fetchImpl?: typeof fetch,
+    private readonly log: (line: string) => void = (line) => console.log(line),
+  ) {
+    this.intent = new AppserviceIntent(cfg, fetchImpl);
+    this.transactions = new TransactionHandler({
+      hsToken: cfg.hsToken,
+      onEvent: (event) => this.onEvent(event),
+      onError: (error, txnId) => this.log(`txn ${txnId} handler error: ${String(error)}`),
+    });
+  }
+
+  /** v1: the daemon only observes; room logic lives in the agent-comms daemons. */
+  private onEvent(event: MatrixEvent): void {
+    if (event.type === 'm.room.message') {
+      this.log(
+        `event ${event.event_id ?? '?'} in ${event.room_id ?? '?'} from ${event.sender ?? '?'}`,
+      );
+    }
+  }
+
+  private bridgeAuthorized(authorizationHeader: string | undefined): boolean {
+    if (!authorizationHeader?.startsWith('Bearer ')) return false;
+    const presented = authorizationHeader.slice('Bearer '.length);
+    return this.cfg.bridgeTokens.some((token) => safeEqual(presented, token));
+  }
+
+  async handle(req: DaemonRequest): Promise<DaemonResponse> {
+    if (req.method === 'GET' && req.path === '/health') {
+      return { status: 200, body: { ok: true } };
+    }
+
+    const txnMatch = req.method === 'PUT' ? TXN_PATH.exec(req.path) : null;
+    if (txnMatch?.[1] !== undefined) {
+      return this.transactions.handle(txnMatch[1], req.body, {
+        authorizationHeader: req.authorizationHeader,
+        accessTokenParam: req.searchParams.get('access_token') ?? undefined,
+      });
+    }
+
+    if (req.path.startsWith('/bridge/v1/')) {
+      if (!this.bridgeAuthorized(req.authorizationHeader)) {
+        return { status: 403, body: { errcode: 'M_FORBIDDEN', error: 'bad bridge token' } };
+      }
+      try {
+        if (req.method === 'POST' && req.path === '/bridge/v1/messages') {
+          validateBridgeMessage(req.body);
+          const eventId = await this.intent.sendAsAgent({
+            roomId: req.body.room_id,
+            agent: req.body.agent,
+            body: req.body.body,
+            threadRoot: req.body.thread_root,
+            msgtype: req.body.msgtype,
+            extraContent: req.body.extra_content,
+          });
+          return { status: 200, body: { event_id: eventId ?? null } };
+        }
+        if (req.method === 'POST' && req.path === '/bridge/v1/typing') {
+          validateBridgeTyping(req.body);
+          await this.intent.setTyping(req.body.room_id, req.body.agent, req.body.typing);
+          return { status: 200, body: {} };
+        }
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        this.log(`bridge error ${req.method} ${req.path}: ${message}`);
+        return { status: 400, body: { error: message } };
+      }
+      // Explicit: never fall out of the authenticated bridge block, so future
+      // sub-paths cannot accidentally route around the auth guard above.
+      return { status: 405, body: { error: 'unsupported bridge method/path' } };
+    }
+
+    return { status: 404, body: { error: 'not found' } };
+  }
+}

apps/appservice/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}

docker/appservice.Dockerfile

@@ -0,0 +1,28 @@
+FROM node:22-alpine AS base
+ENV PNPM_HOME="/pnpm"
+ENV PATH="$PNPM_HOME:$PATH"
+RUN corepack enable
+
+FROM base AS builder
+WORKDIR /app
+# Copy workspace manifests first for layer-cached install
+COPY pnpm-workspace.yaml pnpm-lock.yaml package.json ./
+COPY apps/appservice/package.json ./apps/appservice/
+COPY packages/ ./packages/
+COPY plugins/ ./plugins/
+RUN pnpm install --frozen-lockfile
+COPY . .
+RUN pnpm turbo run build --filter @mosaicstack/mosaic-as...
+RUN pnpm --filter @mosaicstack/mosaic-as --prod deploy --legacy /deploy
+
+FROM base AS runner
+WORKDIR /app
+ENV NODE_ENV=production
+COPY --from=builder /deploy/node_modules ./node_modules
+COPY --from=builder /deploy/package.json ./package.json
+COPY --from=builder /app/apps/appservice/dist ./dist
+USER node
+EXPOSE 8008
+HEALTHCHECK --interval=30s --timeout=5s --start-period=15s --retries=5 \
+  CMD ["node", "-e", "require('http').get('http://127.0.0.1:8008/health',r=>process.exit(r.statusCode===200?0:1)).on('error',()=>process.exit(1))"]
+CMD ["node", "dist/main.js"]

packages/appservice/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@mosaicstack/appservice",
+  "version": "0.0.1",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "https://git.mosaicstack.dev/mosaicstack/stack.git",
+    "directory": "packages/appservice"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "lint": "eslint src",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run --passWithNoTests"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.8.0",
+    "vitest": "^2.0.0"
+  },
+  "publishConfig": {
+    "registry": "https://git.mosaicstack.dev/api/packages/mosaicstack/npm/",
+    "access": "public"
+  },
+  "files": [
+    "dist"
+  ]
+}

packages/appservice/src/__tests__/appservice.test.ts

@@ -0,0 +1,230 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import { validateBridgeMessage, validateBridgeTyping } from '../bridge.dto.js';
+import { AppserviceIntent, MatrixApiError } from '../intent.js';
+import { buildRegistration, registrationToYaml } from '../registration.js';
+import { TransactionHandler } from '../transactions.js';
+import type { AppserviceConfig, MatrixEvent } from '../types.js';
+
+const cfg: AppserviceConfig = {
+  homeserverUrl: 'https://hs.example',
+  domain: 'hs.example',
+  asToken: 'as-secret',
+  hsToken: 'hs-secret',
+};
+
+const jsonResponse = (status: number, body: unknown): Response =>
+  new Response(JSON.stringify(body), { status, headers: { 'Content-Type': 'application/json' } });
+
+describe('TransactionHandler', () => {
+  const makeHandler = (onEvent = vi.fn()) => ({
+    onEvent,
+    handler: new TransactionHandler({ hsToken: 'hs-secret', onEvent }),
+  });
+
+  it('rejects a bad hs_token with M_FORBIDDEN', async () => {
+    const { handler, onEvent } = makeHandler();
+    const res = await handler.handle(
+      't1',
+      { events: [{ type: 'm.room.message' }] },
+      { authorizationHeader: 'Bearer wrong' },
+    );
+    expect(res.status).toBe(403);
+    expect(res.body.errcode).toBe('M_FORBIDDEN');
+    expect(onEvent).not.toHaveBeenCalled();
+  });
+
+  it('accepts Bearer auth and legacy access_token param', async () => {
+    const { handler } = makeHandler();
+    expect(
+      (await handler.handle('t1', { events: [] }, { authorizationHeader: 'Bearer hs-secret' }))
+        .status,
+    ).toBe(200);
+    expect(
+      (await handler.handle('t2', { events: [] }, { accessTokenParam: 'hs-secret' })).status,
+    ).toBe(200);
+  });
+
+  it('processes events once per txnId (idempotent retries)', async () => {
+    const { handler, onEvent } = makeHandler();
+    const body = { events: [{ type: 'm.room.message', event_id: '$e1' }] };
+    await handler.handle('t1', body, { authorizationHeader: 'Bearer hs-secret' });
+    const retry = await handler.handle('t1', body, { authorizationHeader: 'Bearer hs-secret' });
+    expect(retry.status).toBe(200);
+    expect(onEvent).toHaveBeenCalledTimes(1);
+  });
+
+  it('a throwing event handler does not fail the transaction', async () => {
+    const onError = vi.fn();
+    const handler = new TransactionHandler({
+      hsToken: 'hs-secret',
+      onEvent: () => {
+        throw new Error('boom');
+      },
+      onError,
+    });
+    const res = await handler.handle(
+      't1',
+      { events: [{ type: 'x' }, { type: 'y' }] },
+      { authorizationHeader: 'Bearer hs-secret' },
+    );
+    expect(res.status).toBe(200);
+    expect(onError).toHaveBeenCalledTimes(2);
+  });
+});
+
+describe('AppserviceIntent', () => {
+  it('derives namespaced user ids and rejects bad slugs', () => {
+    const intent = new AppserviceIntent(cfg);
+    expect(intent.agentUserId('pi0-web1')).toBe('@agent-pi0-web1:hs.example');
+    expect(intent.agentUserId('Pi0-Web1')).toBe('@agent-pi0-web1:hs.example');
+    expect(() => intent.agentUserId('../evil')).toThrow();
+    expect(() => intent.agentUserId('')).toThrow();
+  });
+
+  it('uses uuid transaction ids', async () => {
+    const calls: string[] = [];
+    const fetchMock = vi.fn(async (input: URL | string) => {
+      calls.push(new URL(String(input)).pathname);
+      return jsonResponse(200, {});
+    });
+    const intent = new AppserviceIntent(cfg, fetchMock as unknown as typeof fetch);
+    await intent.sendAsAgent({ roomId: '!r:hs.example', agent: 'pi0', body: 'x' });
+    const send = calls.find((p) => p.includes('/send/m.room.message/'));
+    expect(send).toMatch(/mosaic-as-[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/);
+  });
+
+  it('registers once, impersonates via user_id, threads replies', async () => {
+    const calls: Array<{ url: URL; init: RequestInit }> = [];
+    const fetchMock = vi.fn(async (input: URL | string, init?: RequestInit) => {
+      calls.push({ url: new URL(String(input)), init: init ?? {} });
+      return jsonResponse(200, { event_id: '$sent' });
+    });
+    const intent = new AppserviceIntent(cfg, fetchMock as unknown as typeof fetch);
+
+    const eventId = await intent.sendAsAgent({
+      roomId: '!room:hs.example',
+      agent: 'pi0-web1',
+      body: 'hello',
+      threadRoot: '$req',
+    });
+    await intent.sendAsAgent({ roomId: '!room:hs.example', agent: 'pi0-web1', body: 'again' });
+
+    expect(eventId).toBe('$sent');
+    const paths = calls.map((c) => c.url.pathname);
+    expect(paths.filter((p) => p.endsWith('/register'))).toHaveLength(1); // cached
+    expect(paths.filter((p) => p.includes('/join'))).toHaveLength(1); // cached
+
+    const send = calls.find((c) => c.url.pathname.includes('/send/m.room.message/'));
+    expect(send).toBeDefined();
+    expect(send!.url.searchParams.get('user_id')).toBe('@agent-pi0-web1:hs.example');
+    const content = JSON.parse(String(send!.init.body)) as Record<string, unknown>;
+    const rel = content['m.relates_to'] as Record<string, unknown>;
+    expect(rel.rel_type).toBe('m.thread');
+    expect(rel.event_id).toBe('$req');
+    expect(rel.is_falling_back).toBe(true);
+    expect(
+      calls.every(
+        (c) => (c.init.headers as Record<string, string>).Authorization === 'Bearer as-secret',
+      ),
+    ).toBe(true);
+  });
+
+  it('tolerates M_USER_IN_USE and surfaces other register errors', async () => {
+    const inUse = vi.fn(async () =>
+      jsonResponse(400, { errcode: 'M_USER_IN_USE', error: 'taken' }),
+    );
+    const intent = new AppserviceIntent(cfg, inUse as unknown as typeof fetch);
+    await expect(intent.ensureRegistered('pi0-web1')).resolves.toBe('@agent-pi0-web1:hs.example');
+
+    const denied = vi.fn(async () =>
+      jsonResponse(401, { errcode: 'M_UNKNOWN_TOKEN', error: 'nope' }),
+    );
+    const intent2 = new AppserviceIntent(cfg, denied as unknown as typeof fetch);
+    await expect(intent2.ensureRegistered('pi0-web1')).rejects.toThrow(MatrixApiError);
+  });
+
+  it('invites then joins on M_FORBIDDEN join', async () => {
+    const paths: string[] = [];
+    const fetchMock = vi.fn(async (input: URL | string) => {
+      const url = new URL(String(input));
+      paths.push(url.pathname);
+      if (url.pathname.endsWith('/join') && paths.filter((p) => p.endsWith('/join')).length === 1) {
+        return jsonResponse(403, { errcode: 'M_FORBIDDEN', error: 'not invited' });
+      }
+      return jsonResponse(200, {});
+    });
+    const intent = new AppserviceIntent(cfg, fetchMock as unknown as typeof fetch);
+    await intent.ensureJoined('!room:hs.example', 'pi0-web1');
+    expect(paths.filter((p) => p.endsWith('/invite'))).toHaveLength(1);
+    expect(paths.filter((p) => p.endsWith('/join'))).toHaveLength(2);
+  });
+});
+
+describe('registration', () => {
+  it('builds an exclusive escaped user namespace', () => {
+    const reg = buildRegistration(cfg, { url: 'http://mosaic-as:8008' });
+    expect(reg.namespaces.users[0]).toEqual({
+      regex: '@agent-.*:hs\\.example',
+      exclusive: true,
+    });
+    expect(reg.rate_limited).toBe(false);
+    const yaml = registrationToYaml(reg);
+    expect(yaml).toContain("sender_localpart: 'mosaic-as'");
+    expect(yaml).toContain("as_token: 'as-secret'");
+    expect(yaml).toContain('exclusive: true');
+  });
+});
+
+describe('registration hardening', () => {
+  it('rejects control characters in registration values', () => {
+    const reg = buildRegistration(
+      { ...cfg, asToken: 'abc\nhttp_injected: true' },
+      { url: 'http://mosaic-as:8008' },
+    );
+    expect(() => registrationToYaml(reg)).toThrow(/control characters/);
+  });
+
+  it('escapes single quotes in token values', () => {
+    const reg = buildRegistration({ ...cfg, asToken: "it's" }, { url: 'http://mosaic-as:8008' });
+    expect(registrationToYaml(reg)).toContain("as_token: 'it''s'");
+  });
+});
+
+describe('bridge DTOs', () => {
+  it('validates message and typing payloads', () => {
+    expect(() =>
+      validateBridgeMessage({ room_id: '!r:hs', agent: 'pi0', body: 'x' }),
+    ).not.toThrow();
+    expect(() => validateBridgeMessage({ room_id: 'bad', agent: 'pi0', body: 'x' })).toThrow();
+    expect(() => validateBridgeMessage({ room_id: '!r:hs', agent: '', body: 'x' })).toThrow();
+    expect(() => validateBridgeMessage({ room_id: '!r:hs', agent: '../evil', body: 'x' })).toThrow(
+      /agent must match/,
+    );
+    expect(() =>
+      validateBridgeTyping({ room_id: '!r:hs', agent: 'pi0', typing: true }),
+    ).not.toThrow();
+    expect(() => validateBridgeTyping({ room_id: '!r:hs', agent: 'pi0', typing: 'yes' })).toThrow();
+  });
+});
+
+describe('event shape', () => {
+  it('transaction events flow through to the handler', async () => {
+    const seen: MatrixEvent[] = [];
+    const handler = new TransactionHandler({
+      hsToken: 'hs-secret',
+      onEvent: (e) => void seen.push(e),
+    });
+    await handler.handle(
+      't1',
+      {
+        events: [
+          { type: 'm.room.message', room_id: '!r:hs', sender: '@u:hs', content: { body: 'hi' } },
+        ],
+      },
+      { authorizationHeader: 'Bearer hs-secret' },
+    );
+    expect(seen).toHaveLength(1);
+    expect(seen[0]!.content?.body).toBe('hi');
+  });
+});

packages/appservice/src/bridge.dto.ts

@@ -0,0 +1,52 @@
+/** DTOs for the internal bridge API consumed by agent-comms host daemons. */
+
+export interface BridgeMessageDto {
+  room_id: string;
+  /** Agent slug (localpart suffix), e.g. "pi0-web1". */
+  agent: string;
+  body: string;
+  thread_root?: string;
+  msgtype?: string;
+  /** Optional protocol payload merged into content (e.g. org.uscllc.agent). */
+  extra_content?: Record<string, unknown>;
+}
+
+export interface BridgeTypingDto {
+  room_id: string;
+  agent: string;
+  typing: boolean;
+}
+
+const AGENT_SLUG_RE = /^[a-z0-9][a-z0-9_.-]*$/;
+
+const assertAgentSlug = (agent: unknown): void => {
+  if (typeof agent !== 'string' || !AGENT_SLUG_RE.test(agent.toLowerCase())) {
+    throw new Error('agent must match [a-z0-9][a-z0-9_.-]*');
+  }
+};
+
+export function validateBridgeMessage(input: unknown): asserts input is BridgeMessageDto {
+  const o = input as Partial<BridgeMessageDto> | null | undefined;
+  if (!o || typeof o !== 'object') throw new Error('payload must be an object');
+  if (typeof o.room_id !== 'string' || !o.room_id.startsWith('!'))
+    throw new Error('room_id must be a Matrix room id');
+  assertAgentSlug(o.agent);
+  if (typeof o.body !== 'string') throw new Error('body must be a string');
+  if (o.thread_root !== undefined && typeof o.thread_root !== 'string')
+    throw new Error('thread_root must be a string');
+  if (
+    o.extra_content !== undefined &&
+    (typeof o.extra_content !== 'object' || o.extra_content === null)
+  ) {
+    throw new Error('extra_content must be an object');
+  }
+}
+
+export function validateBridgeTyping(input: unknown): asserts input is BridgeTypingDto {
+  const o = input as Partial<BridgeTypingDto> | null | undefined;
+  if (!o || typeof o !== 'object') throw new Error('payload must be an object');
+  if (typeof o.room_id !== 'string' || !o.room_id.startsWith('!'))
+    throw new Error('room_id must be a Matrix room id');
+  assertAgentSlug(o.agent);
+  if (typeof o.typing !== 'boolean') throw new Error('typing must be a boolean');
+}

packages/appservice/src/index.ts

@@ -0,0 +1,15 @@
+export { AppserviceIntent, MatrixApiError } from './intent.js';
+export type { SendMessageOptions } from './intent.js';
+export { TransactionHandler } from './transactions.js';
+export type { TransactionHandlerOptions } from './transactions.js';
+export { buildRegistration, registrationToYaml } from './registration.js';
+export type { RegistrationOptions } from './registration.js';
+export { validateBridgeMessage, validateBridgeTyping } from './bridge.dto.js';
+export type { BridgeMessageDto, BridgeTypingDto } from './bridge.dto.js';
+export type {
+  AppserviceConfig,
+  EventHandler,
+  HandlerResult,
+  MatrixEvent,
+  Transaction,
+} from './types.js';

packages/appservice/src/intent.ts

@@ -0,0 +1,184 @@
+import crypto from 'node:crypto';
+
+import type { AppserviceConfig } from './types.js';
+
+export interface SendMessageOptions {
+  roomId: string;
+  /** Agent slug, e.g. "pi0-web1" -> @agent-pi0-web1:domain */
+  agent: string;
+  body: string;
+  /** Request event id to thread off (m.thread, spec v1.4). */
+  threadRoot?: string;
+  msgtype?: string;
+  /** Extra content keys merged into the message content (e.g. org.uscllc.agent). */
+  extraContent?: Record<string, unknown>;
+}
+
+export class MatrixApiError extends Error {
+  constructor(
+    readonly status: number,
+    readonly errcode: string | undefined,
+    message: string,
+  ) {
+    super(message);
+    this.name = 'MatrixApiError';
+  }
+}
+
+type FetchLike = typeof fetch;
+
+/**
+ * Acts on the homeserver as appservice-namespaced virtual users
+ * (Application Service API: as_token auth + user_id impersonation).
+ */
+export class AppserviceIntent {
+  private readonly registered = new Set<string>();
+  private readonly joined = new Set<string>();
+  private readonly fetchImpl: FetchLike;
+
+  constructor(
+    private readonly cfg: AppserviceConfig,
+    fetchImpl?: FetchLike,
+  ) {
+    this.fetchImpl = fetchImpl ?? fetch;
+  }
+
+  get userPrefix(): string {
+    return this.cfg.userPrefix ?? 'agent-';
+  }
+
+  get senderUserId(): string {
+    return `@${this.cfg.senderLocalpart ?? 'mosaic-as'}:${this.cfg.domain}`;
+  }
+
+  agentLocalpart(agent: string): string {
+    const slug = agent.toLowerCase();
+    if (!/^[a-z0-9][a-z0-9_.-]*$/.test(slug)) {
+      throw new Error(`invalid agent slug: ${agent}`);
+    }
+    return `${this.userPrefix}${slug}`;
+  }
+
+  agentUserId(agent: string): string {
+    return `@${this.agentLocalpart(agent)}:${this.cfg.domain}`;
+  }
+
+  private async request(
+    method: string,
+    path: string,
+    options: { userId?: string; body?: unknown } = {},
+  ): Promise<Record<string, unknown>> {
+    const url = new URL(this.cfg.homeserverUrl.replace(/\/$/, '') + path);
+    if (options.userId) {
+      url.searchParams.set('user_id', options.userId);
+    }
+    const res = await this.fetchImpl(url, {
+      method,
+      headers: {
+        Authorization: `Bearer ${this.cfg.asToken}`,
+        'Content-Type': 'application/json',
+      },
+      body: options.body === undefined ? undefined : JSON.stringify(options.body),
+    });
+    const text = await res.text();
+    const data = (text ? JSON.parse(text) : {}) as Record<string, unknown>;
+    if (!res.ok) {
+      throw new MatrixApiError(
+        res.status,
+        typeof data.errcode === 'string' ? data.errcode : undefined,
+        `${method} ${path} -> ${res.status}: ${text.slice(0, 300)}`,
+      );
+    }
+    return data;
+  }
+
+  /** Register the virtual user if it does not exist yet. Idempotent. */
+  async ensureRegistered(agent: string): Promise<string> {
+    const localpart = this.agentLocalpart(agent);
+    const userId = this.agentUserId(agent);
+    if (this.registered.has(userId)) return userId;
+    try {
+      await this.request('POST', '/_matrix/client/v3/register', {
+        body: { type: 'm.login.application_service', username: localpart },
+      });
+    } catch (err) {
+      if (!(err instanceof MatrixApiError && err.errcode === 'M_USER_IN_USE')) {
+        throw err;
+      }
+    }
+    this.registered.add(userId);
+    return userId;
+  }
+
+  /** Join the agent to a room; on invite-only rooms the AS sender invites first. */
+  async ensureJoined(roomId: string, agent: string): Promise<void> {
+    const userId = await this.ensureRegistered(agent);
+    const key = `${userId} ${roomId}`;
+    if (this.joined.has(key)) return;
+    const room = encodeURIComponent(roomId);
+    try {
+      await this.request('POST', `/_matrix/client/v3/rooms/${room}/join`, { userId, body: {} });
+    } catch (err) {
+      if (!(err instanceof MatrixApiError && err.errcode === 'M_FORBIDDEN')) throw err;
+      await this.request('POST', `/_matrix/client/v3/rooms/${room}/invite`, {
+        userId: this.senderUserId,
+        body: { user_id: userId },
+      });
+      await this.request('POST', `/_matrix/client/v3/rooms/${room}/join`, { userId, body: {} });
+    }
+    this.joined.add(key);
+  }
+
+  /** Send a message AS the agent's virtual user. */
+  async sendAsAgent(options: SendMessageOptions): Promise<string | undefined> {
+    const userId = this.agentUserId(options.agent);
+    await this.ensureJoined(options.roomId, options.agent);
+    const content: Record<string, unknown> = {
+      msgtype: options.msgtype ?? 'm.text',
+      body: options.body,
+      ...options.extraContent,
+    };
+    if (options.threadRoot) {
+      content['m.relates_to'] = {
+        rel_type: 'm.thread',
+        event_id: options.threadRoot,
+        is_falling_back: true,
+        'm.in_reply_to': { event_id: options.threadRoot },
+      };
+    }
+    const txn = `mosaic-as-${crypto.randomUUID()}`;
+    const room = encodeURIComponent(options.roomId);
+    const res = await this.request(
+      'PUT',
+      `/_matrix/client/v3/rooms/${room}/send/m.room.message/${txn}`,
+      { userId, body: content },
+    );
+    return typeof res.event_id === 'string' ? res.event_id : undefined;
+  }
+
+  /** Set the agent's typing indicator in a room. */
+  async setTyping(
+    roomId: string,
+    agent: string,
+    typing: boolean,
+    timeoutMs = 30000,
+  ): Promise<void> {
+    const userId = await this.ensureRegistered(agent);
+    const room = encodeURIComponent(roomId);
+    const user = encodeURIComponent(userId);
+    await this.request('PUT', `/_matrix/client/v3/rooms/${room}/typing/${user}`, {
+      userId,
+      body: typing ? { typing: true, timeout: timeoutMs } : { typing: false },
+    });
+  }
+
+  /** Set display name for an agent's virtual user. */
+  async setDisplayName(agent: string, displayName: string): Promise<void> {
+    const userId = await this.ensureRegistered(agent);
+    const user = encodeURIComponent(userId);
+    await this.request('PUT', `/_matrix/client/v3/profile/${user}/displayname`, {
+      userId,
+      body: { displayname: displayName },
+    });
+  }
+}

packages/appservice/src/registration.ts

@@ -0,0 +1,76 @@
+import type { AppserviceConfig } from './types.js';
+
+export interface RegistrationOptions {
+  /** Unique appservice id in Synapse. Default: "mosaic-as". */
+  id?: string;
+  /** URL where Synapse reaches the appservice, e.g. http://mosaic-as:8008 */
+  url: string;
+  /** Alias namespace regex prefix. Default: "#mosaic-". */
+  aliasPrefix?: string;
+}
+
+const escapeRegex = (value: string): string => value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+/**
+ * Build the Synapse appservice registration document (mosaic-as.yaml).
+ * Deployment (infrastructure repo) serializes this to YAML and mounts it via
+ * app_service_config_files.
+ */
+export function buildRegistration(cfg: AppserviceConfig, options: RegistrationOptions) {
+  const prefix = cfg.userPrefix ?? 'agent-';
+  return {
+    id: options.id ?? 'mosaic-as',
+    url: options.url,
+    as_token: cfg.asToken,
+    hs_token: cfg.hsToken,
+    sender_localpart: cfg.senderLocalpart ?? 'mosaic-as',
+    rate_limited: false,
+    namespaces: {
+      users: [
+        {
+          regex: `@${escapeRegex(prefix)}.*:${escapeRegex(cfg.domain)}`,
+          exclusive: true,
+        },
+      ],
+      aliases: [
+        {
+          regex: `${escapeRegex(options.aliasPrefix ?? '#mosaic-')}.*:${escapeRegex(cfg.domain)}`,
+          exclusive: false,
+        },
+      ],
+      rooms: [],
+    },
+  };
+}
+
+const assertYamlSafe = (field: string, value: string): string => {
+  // Tokens/urls/ids are single-line opaque strings; control characters would
+  // let a crafted value terminate the scalar and inject YAML keys.
+  if (/[\r\n\x00-\x08\x0b-\x1f]/.test(value)) {
+    throw new Error(`registration field ${field} contains control characters`);
+  }
+  return value.replace(/'/g, "''");
+};
+
+/** Minimal YAML serialization for the flat registration document. */
+export function registrationToYaml(registration: ReturnType<typeof buildRegistration>): string {
+  const ns = registration.namespaces;
+  const nsBlock = (entries: Array<{ regex: string; exclusive: boolean }>): string =>
+    entries.length === 0
+      ? ' []'
+      : '\n' +
+        entries.map((e) => `    - regex: '${e.regex}'\n      exclusive: ${e.exclusive}`).join('\n');
+  return [
+    `id: '${assertYamlSafe('id', registration.id)}'`,
+    `url: '${assertYamlSafe('url', registration.url)}'`,
+    `as_token: '${assertYamlSafe('as_token', registration.as_token)}'`,
+    `hs_token: '${assertYamlSafe('hs_token', registration.hs_token)}'`,
+    `sender_localpart: '${assertYamlSafe('sender_localpart', registration.sender_localpart)}'`,
+    `rate_limited: ${registration.rate_limited}`,
+    'namespaces:',
+    `  users:${nsBlock(ns.users)}`,
+    `  aliases:${nsBlock(ns.aliases)}`,
+    `  rooms:${nsBlock(ns.rooms)}`,
+    '',
+  ].join('\n');
+}

packages/appservice/src/transactions.ts

@@ -0,0 +1,89 @@
+import { timingSafeEqual } from 'node:crypto';
+
+import type { EventHandler, HandlerResult, Transaction } from './types.js';
+
+const MAX_SEEN_TXN_IDS = 1000;
+
+function safeTokenCompare(presented: string | undefined, expected: string): boolean {
+  if (presented === undefined) return false;
+  const a = Buffer.from(presented);
+  const b = Buffer.from(expected);
+  if (a.length !== b.length) {
+    // Compare against a same-length dummy so length is not a timing oracle.
+    timingSafeEqual(a, Buffer.alloc(a.length));
+    return false;
+  }
+  return timingSafeEqual(a, b);
+}
+
+export interface TransactionHandlerOptions {
+  hsToken: string;
+  onEvent: EventHandler;
+  /** Called for handler errors; events are at-most-once, errors must not 500. */
+  onError?: (error: unknown, txnId: string) => void;
+}
+
+/**
+ * Framework-agnostic handler for the Application Service transactions API
+ * (PUT /_matrix/app/v1/transactions/{txnId}). Host apps (Fastify/Nest) wrap
+ * this in a route.
+ *
+ * Spec requirements covered: hs_token verification (Authorization: Bearer,
+ * with legacy ?access_token fallback), txnId idempotency, always-200 on
+ * accepted transactions (homeserver retries on any other status).
+ *
+ * KNOWN LIMITATION: the txnId dedupe ring is in-process memory only. After a
+ * restart the homeserver may redeliver pending transactions — event handlers
+ * must be idempotent (delivery is at-least-once across process lifetimes).
+ */
+export class TransactionHandler {
+  private readonly seen: string[] = [];
+  private readonly seenSet = new Set<string>();
+
+  constructor(private readonly options: TransactionHandlerOptions) {}
+
+  authorized(
+    authorizationHeader: string | undefined,
+    accessTokenParam: string | undefined,
+  ): boolean {
+    const bearer = authorizationHeader?.startsWith('Bearer ')
+      ? authorizationHeader.slice('Bearer '.length)
+      : undefined;
+    const presented = bearer ?? accessTokenParam;
+    return safeTokenCompare(presented, this.options.hsToken);
+  }
+
+  async handle(
+    txnId: string,
+    body: unknown,
+    auth: { authorizationHeader?: string; accessTokenParam?: string },
+  ): Promise<HandlerResult> {
+    if (!this.authorized(auth.authorizationHeader, auth.accessTokenParam)) {
+      return { status: 403, body: { errcode: 'M_FORBIDDEN', error: 'bad hs_token' } };
+    }
+    if (this.seenSet.has(txnId)) {
+      return { status: 200, body: {} };
+    }
+    this.markSeen(txnId);
+    const txn = (body ?? {}) as Partial<Transaction>;
+    for (const event of txn.events ?? []) {
+      try {
+        await this.options.onEvent(event);
+      } catch (error) {
+        // A failing handler must not fail the transaction: the homeserver
+        // would retry the whole batch forever.
+        this.options.onError?.(error, txnId);
+      }
+    }
+    return { status: 200, body: {} };
+  }
+
+  private markSeen(txnId: string): void {
+    this.seen.push(txnId);
+    this.seenSet.add(txnId);
+    while (this.seen.length > MAX_SEEN_TXN_IDS) {
+      const evicted = this.seen.shift();
+      if (evicted !== undefined) this.seenSet.delete(evicted);
+    }
+  }
+}

packages/appservice/src/types.ts

@@ -0,0 +1,35 @@
+export interface AppserviceConfig {
+  /** Homeserver client-server API base, e.g. https://chat.uscllc.com */
+  homeserverUrl: string;
+  /** Server name used in user IDs, e.g. chat.uscllc.com */
+  domain: string;
+  /** Token the appservice presents to the homeserver (as_token). */
+  asToken: string;
+  /** Token the homeserver presents to the appservice (hs_token). */
+  hsToken: string;
+  /** Localpart prefix owned by this appservice. Default: "agent-". */
+  userPrefix?: string;
+  /** The appservice's own sender user localpart. Default: "mosaic-as". */
+  senderLocalpart?: string;
+}
+
+export interface MatrixEvent {
+  type: string;
+  event_id?: string;
+  room_id?: string;
+  sender?: string;
+  state_key?: string;
+  content?: Record<string, unknown>;
+  origin_server_ts?: number;
+}
+
+export interface Transaction {
+  events: MatrixEvent[];
+}
+
+export type EventHandler = (event: MatrixEvent) => void | Promise<void>;
+
+export interface HandlerResult {
+  status: number;
+  body: Record<string, unknown>;
+}

packages/appservice/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}

packages/mosaic/framework/tools/git/ci-queue-wait.sh

@@ -137,7 +137,7 @@ gitea_get_branch_head_sha() {
     local branch="$3"
     local token="$4"
     local url="https://${host}/api/v1/repos/${repo}/branches/${branch}"
-    curl -fsS -H "Authorization: token ${token}" "$url" | python3 -c '
+    curl -fsSL -H "Authorization: token ${token}" "$url" | python3 -c '
 import json, sys
 data = json.load(sys.stdin)
 commit = data.get("commit") or {}
@@ -151,7 +151,7 @@ gitea_get_commit_status_json() {
     local sha="$3"
     local token="$4"
     local url="https://${host}/api/v1/repos/${repo}/commits/${sha}/status"
-    curl -fsS -H "Authorization: token ${token}" "$url"
+    curl -fsSL -H "Authorization: token ${token}" "$url"
 }
 
 while [[ $# -gt 0 ]]; do

packages/mosaic/framework/tools/git/pr-ci-wait.sh

@@ -124,7 +124,7 @@ gitea_get_pr_head_sha() {
     local repo="$2"
     local token="$3"
     local url="https://${host}/api/v1/repos/${repo}/pulls/${PR_NUMBER}"
-    curl -fsS -H "Authorization: token ${token}" "$url" | python3 -c '
+    curl -fsSL -H "Authorization: token ${token}" "$url" | python3 -c '
 import json, sys
 data = json.load(sys.stdin)
 print((data.get("head") or {}).get("sha", ""))
@@ -137,7 +137,7 @@ gitea_get_commit_status_json() {
     local token="$3"
     local sha="$4"
     local url="https://${host}/api/v1/repos/${repo}/commits/${sha}/status"
-    curl -fsS -H "Authorization: token ${token}" "$url"
+    curl -fsSL -H "Authorization: token ${token}" "$url"
 }
 
 while [[ $# -gt 0 ]]; do

packages/mosaic/src/commands/git-wrapper-redirects.spec.ts

@@ -0,0 +1,22 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { describe, expect, it } from 'vitest';
+
+const packageRoot = join(import.meta.dirname, '..', '..');
+const gitToolsDir = join(packageRoot, 'framework', 'tools', 'git');
+
+function readGitTool(scriptName: string): string {
+  return readFileSync(join(gitToolsDir, scriptName), 'utf-8');
+}
+
+describe('Gitea git wrapper API calls', () => {
+  it.each(['ci-queue-wait.sh', 'pr-ci-wait.sh'])(
+    '%s follows Gitea API redirects before parsing JSON',
+    (scriptName) => {
+      const script = readGitTool(scriptName);
+
+      expect(script).not.toContain('curl -fsS -H "Authorization: token');
+      expect(script).toContain('curl -fsSL -H "Authorization: token');
+    },
+  );
+});

packages/mosaic/src/commands/launch.spec.ts

@@ -1,6 +1,6 @@
 import { describe, it, expect, vi, beforeEach, afterEach, type MockInstance } from 'vitest';
 import { Command } from 'commander';
-import { registerRuntimeLaunchers, type RuntimeLaunchHandler } from './launch.js';
+import { buildPiSkillArgs, registerRuntimeLaunchers, type RuntimeLaunchHandler } from './launch.js';
 
 /**
  * Tests for the commander wiring between `mosaic <runtime>` / `mosaic yolo <runtime>`
@@ -22,6 +22,8 @@ function buildProgram(handler: RuntimeLaunchHandler): Command {
   return program;
 }
 
+const fakeSkills = ['--skill', '/skills/test-driven-development', '--skill', '/skills/pdf'];
+
 // `process.exit` returns `never`, so vi.spyOn demands a replacement with the
 // same signature. We throw from the mock to short-circuit into test-land.
 const exitThrows = (): never => {
@@ -63,6 +65,30 @@ describe('registerRuntimeLaunchers — non-yolo subcommands', () => {
   });
 });
 
+describe('buildPiSkillArgs', () => {
+  it('defaults to disabling Pi skill discovery to keep startup context small', () => {
+    expect(buildPiSkillArgs([], {}, fakeSkills)).toEqual(['--no-skills']);
+  });
+
+  it('keeps explicit user skills while disabling automatic discovery', () => {
+    expect(buildPiSkillArgs(['--skill', '/tmp/custom'], {}, fakeSkills)).toEqual(['--no-skills']);
+  });
+
+  it('supports legacy all-skills mode without double-loading settings skills', () => {
+    expect(buildPiSkillArgs([], { MOSAIC_PI_SKILL_MODE: 'all' }, fakeSkills)).toEqual([
+      '--no-skills',
+      '--skill',
+      '/skills/test-driven-development',
+      '--skill',
+      '/skills/pdf',
+    ]);
+  });
+
+  it('supports native Pi discovery when explicitly requested', () => {
+    expect(buildPiSkillArgs([], { MOSAIC_PI_SKILL_MODE: 'discover' }, fakeSkills)).toEqual([]);
+  });
+});
+
 describe('registerRuntimeLaunchers — yolo <runtime>', () => {
   let mockExit: MockInstance<typeof process.exit>;
   let mockError: MockInstance<typeof console.error>;

packages/mosaic/src/commands/launch.ts

@@ -447,6 +447,32 @@ function discoverPiSkills(): string[] {
   return args;
 }
 
+type PiSkillMode = 'none' | 'all' | 'discover';
+
+function normalizePiSkillMode(env: NodeJS.ProcessEnv): PiSkillMode {
+  const value = env['MOSAIC_PI_SKILL_MODE']?.trim().toLowerCase();
+  if (value === 'all' || value === 'discover') return value;
+  return 'none';
+}
+
+export function buildPiSkillArgs(
+  _runtimeArgs: string[],
+  env: NodeJS.ProcessEnv = process.env,
+  discoveredSkillArgs: string[] = discoverPiSkills(),
+): string[] {
+  const mode = normalizePiSkillMode(env);
+
+  if (mode === 'discover') {
+    return [];
+  }
+
+  if (mode === 'all') {
+    return ['--no-skills', ...discoveredSkillArgs];
+  }
+
+  return ['--no-skills'];
+}
+
 function discoverPiExtension(): string[] {
   const ext = join(MOSAIC_HOME, 'runtime', 'pi', 'mosaic-extension.ts');
   return existsSync(ext) ? ['--extension', ext] : [];
@@ -523,7 +549,7 @@ function launchRuntime(runtime: RuntimeName, args: string[], yolo: boolean): nev
     case 'pi': {
       const prompt = buildRuntimePrompt('pi');
       const cliArgs = ['--append-system-prompt', prompt];
-      cliArgs.push(...discoverPiSkills());
+      cliArgs.push(...buildPiSkillArgs(args));
       cliArgs.push(...discoverPiExtension());
       if (hasMissionNoArgs) {
         cliArgs.push(missionPrompt);

pnpm-lock.yaml

@@ -39,6 +39,25 @@ importers:
         specifier: ^2.0.0
         version: 2.1.9(@types/node@24.12.0)(jsdom@29.0.0(@noble/hashes@2.0.1))(lightningcss@1.31.1)
 
+  apps/appservice:
+    dependencies:
+      '@mosaicstack/appservice':
+        specifier: workspace:*
+        version: link:../../packages/appservice
+    devDependencies:
+      '@types/node':
+        specifier: ^22.0.0
+        version: 22.19.15
+      tsx:
+        specifier: ^4.19.0
+        version: 4.21.0
+      typescript:
+        specifier: ^5.8.0
+        version: 5.9.3
+      vitest:
+        specifier: ^2.0.0
+        version: 2.1.9(@types/node@22.19.15)(jsdom@29.0.0(@noble/hashes@2.0.1))(lightningcss@1.31.1)
+
   apps/gateway:
     dependencies:
       '@anthropic-ai/sdk':
@@ -297,6 +316,18 @@ importers:
         specifier: ^2.0.0
         version: 2.1.9(@types/node@24.12.0)(jsdom@29.0.0(@noble/hashes@2.0.1))(lightningcss@1.31.1)
 
+  packages/appservice:
+    devDependencies:
+      '@types/node':
+        specifier: ^22.0.0
+        version: 22.19.15
+      typescript:
+        specifier: ^5.8.0
+        version: 5.9.3
+      vitest:
+        specifier: ^2.0.0
+        version: 2.1.9(@types/node@22.19.15)(jsdom@29.0.0(@noble/hashes@2.0.1))(lightningcss@1.31.1)
+
   packages/auth:
     dependencies:
       '@mosaicstack/db':