@zooid/core 0.13.0 → 0.14.0

package/src/transport-context.test.ts

@@ -4,7 +4,9 @@ import type {
   HistoryPage,
   Message,
   Member,
-  ChannelInfo,
+  RoomInfo,
+  SendMessageInput,
+  SendMessageResult,
   ThreadOverviewPage,
 } from './transport-context.js'
 
@@ -20,11 +22,16 @@ describe('TransportContextProvider', () => {
     >()
     expectTypeOf<TransportContextProvider['getThreadHistory']>().returns.resolves.toEqualTypeOf<HistoryPage>()
     expectTypeOf<TransportContextProvider['getChannelMembers']>().returns.resolves.toEqualTypeOf<Member[]>()
-    expectTypeOf<TransportContextProvider['getChannelInfo']>().returns.resolves.toEqualTypeOf<ChannelInfo>()
+    expectTypeOf<TransportContextProvider['getRoomInfo']>().returns.resolves.toEqualTypeOf<RoomInfo>()
+    expectTypeOf<TransportContextProvider['getRooms']>().returns.resolves.toEqualTypeOf<RoomInfo[]>()
+    expectTypeOf<TransportContextProvider['sendMessage']>().parameters.toEqualTypeOf<
+      [SendMessageInput]
+    >()
+    expectTypeOf<TransportContextProvider['sendMessage']>().returns.resolves.toEqualTypeOf<SendMessageResult>()
   })
 
-  it('ChannelInfo.transport is the two-transport MVP union', () => {
-    expectTypeOf<ChannelInfo['transport']>().toEqualTypeOf<'http' | 'matrix'>()
+  it('RoomInfo.transport is the two-transport MVP union', () => {
+    expectTypeOf<RoomInfo['transport']>().toEqualTypeOf<'http' | 'matrix'>()
   })
 
   it('Message and Member carry the is_agent flag', () => {

package/src/transport-context.ts

@@ -27,12 +27,24 @@ export interface Member {
   agent_name?: string
 }
 
-export interface ChannelInfo {
+/** Renamed from ChannelInfo — "channel" is not a Matrix primitive ([[ZOD084]]). */
+export interface RoomInfo {
   id: string
   name: string
   transport: 'http' | 'matrix'
 }
 
+export interface SendMessageInput {
+  room: string
+  thread_id?: string
+  text: string
+}
+
+export interface SendMessageResult {
+  event_id: string
+  thread_id?: string
+}
+
 export interface HistoryPage {
   messages: Message[]
   next_before?: string
@@ -87,5 +99,9 @@ export interface TransportContextProvider {
     opts: HistoryOptions,
   ): Promise<HistoryPage>
   getChannelMembers(channelId: string): Promise<Member[]>
-  getChannelInfo(channelId: string): Promise<ChannelInfo>
+  /** Renamed from getChannelInfo. */
+  getRoomInfo(channelId: string): Promise<RoomInfo>
+  /** Rooms this agent is bound to. Targets for sendMessage. */
+  getRooms(): Promise<RoomInfo[]>
+  sendMessage(input: SendMessageInput): Promise<SendMessageResult>
 }

package/src/triggers-config.test.ts

@@ -0,0 +1,168 @@
+import { describe, it, expect } from 'vitest'
+import { loadZooidConfig } from './config.js'
+
+const base = `
+runtime: local
+transports:
+  matrix:
+    type: matrix
+    homeserver: http://localhost:8448
+    as_token: t
+    hs_token: h
+    user_namespace: '@.*:example.org'
+agents:
+  architect:
+    acp: { preset: opencode }
+    matrix:
+      rooms: ["#ops:example.org"]
+`
+
+const baseTwoAgents = `
+runtime: local
+transports:
+  matrix:
+    type: matrix
+    homeserver: http://localhost:8448
+    as_token: t
+    hs_token: h
+    user_namespace: '@.*:example.org'
+agents:
+  architect:
+    acp: { preset: opencode }
+    matrix:
+      rooms: ["#ops:example.org"]
+  product-manager:
+    acp: { preset: opencode }
+    matrix:
+      rooms: ["#ops:example.org"]
+`
+
+const baseWithHttpAgent = `
+runtime: local
+transports:
+  matrix:
+    type: matrix
+    homeserver: http://localhost:8448
+    as_token: t
+    hs_token: h
+    user_namespace: '@.*:example.org'
+  http-local:
+    type: http
+    port: 8080
+agents:
+  architect:
+    acp: { preset: opencode }
+    matrix:
+      rooms: ["#ops:example.org"]
+  worker:
+    acp: { preset: opencode }
+    http: {}
+`
+
+const withTriggers = (block: string) => `${base}\ntriggers:\n${block}`
+
+const ok = `
+  image-currency:
+    schedule: "0 6 * * 1"
+    as: "@cron:example.org"
+    room: "#ops:example.org"
+    mention: architect
+    text: "Check the pinned agent CLI versions."
+`
+
+describe('triggers: config', () => {
+  it('is optional — a config with no triggers loads and yields an empty map', () => {
+    expect(loadZooidConfig(base).triggers).toEqual({})
+  })
+
+  it('parses a schedule trigger', () => {
+    const t = loadZooidConfig(withTriggers(ok)).triggers['image-currency']
+    expect(t).toEqual({
+      schedule: '0 6 * * 1',
+      as: '@cron:example.org',
+      messages: [
+        { room: '#ops:example.org', mention: 'architect', text: 'Check the pinned agent CLI versions.' },
+      ],
+    })
+  })
+
+  it('accepts a room id as well as an alias', () => {
+    const cfg = loadZooidConfig(withTriggers(ok.replace('"#ops:example.org"', '"!abc:example.org"')))
+    expect(cfg.triggers['image-currency'].messages[0].room).toBe('!abc:example.org')
+  })
+
+  it('rejects run: — the emitter tier was dropped, and a stale config must fail loudly', () => {
+    expect(() =>
+      loadZooidConfig(withTriggers(`${ok}    run: "echo hi"\n`)),
+    ).toThrow(/triggers\.image-currency\.run: is not supported/)
+  })
+
+  it('rejects a mention that names no configured agent', () => {
+    expect(() =>
+      loadZooidConfig(withTriggers(ok.replace('mention: architect', 'mention: nobody'))),
+    ).toThrow(/triggers\.image-currency\.messages\[0\]\.mention: unknown agent "nobody"/)
+  })
+
+  it('rejects an invalid cron expression at load time, not at first fire', () => {
+    expect(() =>
+      loadZooidConfig(withTriggers(ok.replace('"0 6 * * 1"', '"not a cron"'))),
+    ).toThrow(/triggers\.image-currency\.schedule/)
+  })
+
+  it('expands a bare localpart in as: to a full MXID via the sole matrix transport', () => {
+    const cfg = loadZooidConfig(withTriggers(ok.replace('"@cron:example.org"', '"cron"')))
+    expect(cfg.triggers['image-currency'].as).toBe('@cron:example.org')
+  })
+
+  it('expands a short-form @localpart in as: the same way', () => {
+    const cfg = loadZooidConfig(withTriggers(ok.replace('"@cron:example.org"', '"@cron"')))
+    expect(cfg.triggers['image-currency'].as).toBe('@cron:example.org')
+  })
+
+  it('rejects an as: with invalid localpart characters', () => {
+    expect(() =>
+      loadZooidConfig(withTriggers(ok.replace('"@cron:example.org"', '"Not Valid!"'))),
+    ).toThrow(/triggers\.image-currency\.as: must be a full MXID/)
+  })
+
+  it("rejects an as: that resolves to the mentioned agent's own MXID — a self-post never routes back", () => {
+    const block = ok.replace('"@cron:example.org"', '"architect"')
+    expect(() => loadZooidConfig(withTriggers(block))).toThrow(
+      /triggers\.image-currency\.as: must not equal the mentioned agent/,
+    )
+  })
+
+  it("allows as: to impersonate a different agent's own identity — cron-as-a-role", () => {
+    const block = ok.replace('"@cron:example.org"', '"product-manager"')
+    const cfg = loadZooidConfig(`${baseTwoAgents}\ntriggers:\n${block}`)
+    expect(cfg.triggers['image-currency'].as).toBe('@product-manager:example.org')
+  })
+
+  it('rejects mention: of an agent with no matrix: binding', () => {
+    const block = ok.replace('mention: architect', 'mention: worker')
+    expect(() => loadZooidConfig(`${baseWithHttpAgent}\ntriggers:\n${block}`)).toThrow(
+      /triggers\.image-currency\.messages\[0\]\.mention: agent "worker" has no matrix: binding/,
+    )
+  })
+
+  it('requires as, room, mention and text', () => {
+    const indexed = new Set(['room', 'mention', 'text'])
+    for (const field of ['as', 'room', 'mention', 'text']) {
+      const block = ok
+        .split('\n')
+        .filter((l) => !l.trim().startsWith(`${field}:`))
+        .join('\n')
+      const label = indexed.has(field)
+        ? `triggers\\.image-currency\\.messages\\[0\\]\\.${field}`
+        : `triggers\\.image-currency\\.${field}`
+      expect(() => loadZooidConfig(withTriggers(block))).toThrow(new RegExp(label))
+    }
+  })
+
+  it('rejects a trigger with no schedule', () => {
+    const block = ok.split('\n').filter((l) => !l.trim().startsWith('schedule:')).join('\n')
+    expect(() => loadZooidConfig(withTriggers(block))).toThrow(
+      /triggers\.image-currency: must specify schedule:/,
+    )
+  })
+})

package/src/triggers-messages-config.test.ts

@@ -0,0 +1,146 @@
+import { describe, it, expect } from 'vitest'
+import { loadZooidConfig } from './config.js'
+
+const head = `
+runtime: local
+transports:
+  matrix:
+    type: matrix
+    homeserver: http://localhost:8448
+    as_token: t
+    hs_token: h
+    user_namespace: '@.*:example.org'
+agents:
+  product:
+    acp: { preset: opencode }
+    matrix:
+      rooms: ["#product:example.org"]
+  architect:
+    acp: { preset: opencode }
+    matrix:
+      rooms: ["#dev:example.org"]
+`
+
+const flat = `${head}
+triggers:
+  triage:
+    webhook:
+      provider: github
+      secret: "s"
+    as: "@hook:example.org"
+    room: "#product:example.org"
+    mention: product
+    match: 'event == "issues" && body.action == "opened"'
+    text: 'Triage \${body.repository.full_name}#\${body.issue.number}.'
+`
+
+const plural = `${head}
+triggers:
+  github:
+    webhook:
+      provider: github
+      secret: "s"
+    as: "@hook:example.org"
+    messages:
+      - room: "#product:example.org"
+        mention: product
+        match: 'event == "issues" && body.action == "opened"'
+        text: 'Triage it.'
+      - room: "#dev:example.org"
+        mention: architect
+        match: 'event == "pull_request" && body.action == "closed"'
+        text: 'Reconcile it.'
+`
+
+describe('flat form', () => {
+  it('desugars into a single-entry messages list', () => {
+    const t = loadZooidConfig(flat).triggers.triage
+    expect(t.messages).toHaveLength(1)
+    expect(t.messages[0].room).toBe('#product:example.org')
+    expect(t.messages[0].mention).toBe('product')
+    expect(t.messages[0].match).toBe('event == "issues" && body.action == "opened"')
+  })
+
+  // Nothing downstream may branch on which spelling was used.
+  it('leaves no flat room/mention/text on the parsed trigger', () => {
+    const t = loadZooidConfig(flat).triggers.triage as Record<string, unknown>
+    expect(t.room).toBeUndefined()
+    expect(t.mention).toBeUndefined()
+    expect(t.text).toBeUndefined()
+  })
+})
+
+describe('messages form', () => {
+  it('parses several messages', () => {
+    const t = loadZooidConfig(plural).triggers.github
+    expect(t.messages.map((m) => m.mention)).toEqual(['product', 'architect'])
+  })
+
+  it('exposes every declared room, so the bot pool can join them at start', () => {
+    const t = loadZooidConfig(plural).triggers.github
+    expect(t.messages.map((m) => m.room)).toEqual(['#product:example.org', '#dev:example.org'])
+  })
+
+  it('validates each message the same way the flat form is validated', () => {
+    expect(() => loadZooidConfig(plural.replace('mention: architect', 'mention: nobody'))).toThrow(
+      /triggers\.github\.messages\[1\]\.mention: unknown agent "nobody"/,
+    )
+  })
+
+  it('rejects an empty messages list', () => {
+    expect(() => loadZooidConfig(`${head}
+triggers:
+  github:
+    webhook: { provider: github, secret: "s" }
+    as: "@hook:example.org"
+    messages: []
+`)).toThrow(/triggers\.github\.messages: must not be empty/)
+  })
+})
+
+describe('mutual exclusion and validation', () => {
+  it('rejects flat keys together with messages, rather than picking one silently', () => {
+    expect(() => loadZooidConfig(plural.replace('    messages:', '    room: "#product:example.org"\n    messages:'))).toThrow(
+      /triggers\.github: specify either room:\/mention:\/text: or messages:, not both/,
+    )
+  })
+
+  it('rejects match: on a schedule trigger — there is no payload to evaluate', () => {
+    expect(() => loadZooidConfig(`${head}
+triggers:
+  weekly:
+    schedule: "0 6 * * 1"
+    as: "@cron:example.org"
+    room: "#dev:example.org"
+    mention: architect
+    match: 'true'
+    text: 'go'
+`)).toThrow(/triggers\.weekly\.match: only applies to a webhook: trigger/)
+  })
+
+  it('allows messages: on a schedule trigger — one cron, several agents', () => {
+    const cfg = loadZooidConfig(`${head}
+triggers:
+  weekly:
+    schedule: "0 6 * * 1"
+    as: "@cron:example.org"
+    messages:
+      - { room: "#product:example.org", mention: product, text: 'a' }
+      - { room: "#dev:example.org", mention: architect, text: 'b' }
+`)
+    expect(cfg.triggers.weekly.messages).toHaveLength(2)
+  })
+
+  // A typo must fail the daemon at boot, not silently never match.
+  it('rejects a malformed match expression at config load', () => {
+    expect(() => loadZooidConfig(flat.replace("match: 'event == \"issues\" && body.action == \"opened\"'", "match: 'body.action =='"))).toThrow(
+      /triggers\.triage\.messages\[0\]\.match: /,
+    )
+  })
+
+  it('no longer accepts event:', () => {
+    expect(() => loadZooidConfig(flat.replace('      secret: "s"', '      event: issues\n      secret: "s"'))).toThrow(
+      /triggers\.triage\.webhook\.event: no longer supported — use match:/,
+    )
+  })
+})

package/src/triggers-webhook-config.test.ts

@@ -0,0 +1,143 @@
+import { describe, it, expect } from 'vitest'
+import { loadZooidConfig } from './config.js'
+
+const base = `
+runtime: local
+transports:
+  matrix:
+    type: matrix
+    homeserver: http://localhost:8448
+    as_token: t
+    hs_token: h
+    user_namespace: '@.*:example.org'
+agents:
+  product:
+    acp: { preset: opencode }
+    matrix:
+      rooms: ["#product:example.org"]
+triggers:
+  reconcile:
+    webhook:
+      provider: github
+      secret: "topsecret"
+    as: "@hook:example.org"
+    room: "#product:example.org"
+    mention: product
+    text: |
+      A PR merged.
+
+      \${output}
+`
+
+describe('webhook triggers: config', () => {
+  it('parses a webhook trigger', () => {
+    const t = loadZooidConfig(base).triggers.reconcile
+    expect(t.webhook).toEqual({ provider: 'github', secret: 'topsecret' })
+    expect(t.schedule).toBeUndefined()
+  })
+
+  it('no longer accepts event: — use match: instead', () => {
+    expect(() =>
+      loadZooidConfig(base.replace('provider: github', 'provider: github\n      event: pull_request')),
+    ).toThrow(/triggers\.reconcile\.webhook\.event: no longer supported — use match:/)
+  })
+
+  it('rejects a trigger with both schedule and webhook', () => {
+    expect(() =>
+      loadZooidConfig(base.replace('    as: "@hook', '    schedule: "0 6 * * 1"\n    as: "@hook')),
+    ).toThrow(/triggers\.reconcile: specify either schedule: or webhook:, not both/)
+  })
+
+  it('rejects an unknown provider — per-provider verification must exist', () => {
+    expect(() => loadZooidConfig(base.replace('provider: github', 'provider: acme'))).toThrow(
+      /triggers\.reconcile\.webhook\.provider: unknown provider "acme"/,
+    )
+  })
+
+  it('requires a secret — fail closed, never "no secret configured so accept"', () => {
+    expect(() =>
+      loadZooidConfig(base.split('\n').filter((l) => !l.includes('secret:')).join('\n')),
+    ).toThrow(/triggers\.reconcile\.webhook\.secret: is required/)
+  })
+
+  it('interpolates the secret from the environment', () => {
+    process.env.TEST_WH_SECRET = 'from-env'
+    try {
+      const cfg = loadZooidConfig(base.replace('"topsecret"', '${TEST_WH_SECRET}'))
+      expect(cfg.triggers.reconcile.webhook?.secret).toBe('from-env')
+    } finally {
+      delete process.env.TEST_WH_SECRET
+    }
+  })
+})
+
+/**
+ * `custom` is the escape hatch for any signing scheme without a named
+ * provider — ed25519, SHA-1 over sorted params, bespoke timestamped base
+ * strings. It takes a function rather than declarative fields, because a
+ * config language for signing schemes is a mini-DSL that still would not
+ * cover them all.
+ */
+describe('webhook triggers: the custom provider', () => {
+  const custom = (block: string) =>
+    base.replace(
+      `      provider: github
+      secret: "topsecret"`,
+      block,
+    )
+
+  it('resolves the verifier path against the zooid.yaml directory', () => {
+    const t = loadZooidConfig(
+      custom(`      provider: custom
+      verify: ./verifiers/shopify.js
+      secret: "topsecret"`),
+      { configDir: '/srv/workforce' },
+    ).triggers.reconcile
+    expect(t.webhook).toEqual({
+      provider: 'custom',
+      verify: '/srv/workforce/verifiers/shopify.js',
+      secret: 'topsecret',
+    })
+  })
+
+  it('leaves an absolute verifier path alone', () => {
+    const t = loadZooidConfig(
+      custom(`      provider: custom
+      verify: /opt/zooid/verify.js
+      secret: "topsecret"`),
+      { configDir: '/srv/workforce' },
+    ).triggers.reconcile
+    expect(t.webhook?.verify).toBe('/opt/zooid/verify.js')
+  })
+
+  it('requires verify: — there is no built-in scheme to fall back on', () => {
+    expect(() =>
+      loadZooidConfig(
+        custom(`      provider: custom
+      secret: "topsecret"`),
+        { configDir: '/srv/workforce' },
+      ),
+    ).toThrow(/triggers\.reconcile\.webhook\.verify: is required when provider: custom/)
+  })
+
+  it('rejects a relative verifier path with no configDir to resolve against', () => {
+    expect(() =>
+      loadZooidConfig(
+        custom(`      provider: custom
+      verify: ./verify.js
+      secret: "topsecret"`),
+      ),
+    ).toThrow(/triggers\.reconcile\.webhook\.verify: relative path/)
+  })
+
+  it('rejects verify: on a named provider, rather than ignoring it', () => {
+    expect(() =>
+      loadZooidConfig(
+        custom(`      provider: github
+      verify: ./verify.js
+      secret: "topsecret"`),
+        { configDir: '/srv/workforce' },
+      ),
+    ).toThrow(/triggers\.reconcile\.webhook\.verify: only applies to provider: custom/)
+  })
+})

package/src/types.ts

@@ -277,6 +277,8 @@ export interface ZooidConfig {
     pre_turn?: string
     post_turn?: string
   }
+  /** Optional. Map of trigger name → trigger. Empty map when the block is absent. */
+  triggers: Record<string, TriggerConfig>
 }
 
 export interface CliFlags {
@@ -284,3 +286,66 @@ export interface CliFlags {
   /** Container image override (shorthand for container.image). */
   image?: string
 }
+
+/**
+ * A webhook trigger: exposes `POST /_zooid/webhooks/<name>`, verifies an HMAC
+ * signature over the raw request body, and fires like a schedule trigger
+ * once accepted. See [[ZOD082]] §Design 4 and [[ZOD086]].
+ */
+export interface WebhookTriggerConfig {
+  provider: 'github' | 'stripe' | 'slack' | 'standard' | 'custom'
+  /** Required. Interpolated from env — see [[ZOD081]] §Design 4, Secrets. */
+  secret: string
+  /**
+   * `custom` only, required: path to a module exporting the verifier
+   * function, resolved to an absolute path against the zooid.yaml directory
+   * at parse time. The escape hatch for any scheme without a named provider
+   * — ed25519, SHA-1 over sorted params, bespoke timestamped base strings.
+   * Code rather than declarative fields, because a config language for
+   * signing schemes is a security-critical mini-DSL that still would not
+   * cover them all. The daemon imports it at startup — see
+   * `loadCustomVerifiers` in the CLI.
+   */
+  verify?: string
+}
+
+/**
+ * One message a trigger can post: a room, the agent to mention, the body
+ * template, and — webhook triggers only — a CEL `match:` predicate gating
+ * whether this message fires for a given delivery. See [[ZOD085]] §Design 4.
+ */
+export interface TriggerMessage {
+  /** Room id or alias the message goes to. */
+  room: string
+  /** Agent name (key in `agents`) to mention. Structural, never templated — §Design 3. */
+  mention: string
+  /** The message body. Literal for a scheduled trigger; `${...}` is CEL-interpolated for a webhook trigger. */
+  text: string
+  /**
+   * CEL predicate over the delivery (`event`, `body`, `headers`, `output`).
+   * Absent means always fire. Only valid on a `webhook:` trigger — a
+   * schedule trigger has no delivery to evaluate.
+   */
+  match?: string
+}
+
+/**
+ * A trigger: fires on a cron or a webhook delivery and posts one or more
+ * `messages`, each structurally mentioning its agent so the turn starts
+ * through the ordinary message path. No emitter/command tier — see
+ * [[ZOD081]] §Concept.
+ */
+export interface TriggerConfig {
+  /** Cron expression. Mutually exclusive with `webhook:` — exactly one is required. */
+  schedule?: string
+  /** Webhook ingress config. Mutually exclusive with `schedule:` — [[ZOD082]]. */
+  webhook?: WebhookTriggerConfig
+  /** Full MXID the trigger posts as, e.g. `@cron:example.org`. */
+  as: string
+  /**
+   * The messages this trigger can post. A flat `room:`/`mention:`/`text:`/
+   * `match:` at the trigger level desugars into a single-entry list here at
+   * config load — nothing downstream branches on which spelling was used.
+   */
+  messages: TriggerMessage[]
+}