@openparachute/agent 0.1.2 → 0.2.0

package/src/channels/api-translator.test.ts

@@ -1,306 +0,0 @@
-/**
- * Round-trip + validator coverage for the shared channel-wire translator
- * (paraclaw#123). The HTTP and MCP surfaces both depend on this module to
- * keep the wire ↔ DB enums in lockstep — paraclaw#94/#122 was the drift
- * incident that motivated extracting these tests behind one file.
- */
-import { describe, it, expect } from 'vitest';
-
-import type { MessagingGroupAgent } from '../types.js';
-import {
-  ALL_MESSAGES_PATTERN_SENTINEL,
-  apiToDbPatch,
-  dbToApiEngage,
-  dbToApiIgnoredPolicy,
-  dbToApiSenderScope,
-  rowToView,
-  validatePatchInput,
-  type WireJoinRow,
-} from './api-translator.js';
-
-function baseRow(overrides: Partial<WireJoinRow> = {}): WireJoinRow {
-  return {
-    id: 'mga-1',
-    messaging_group_id: 'mg-1',
-    agent_group_id: 'ag-1',
-    engage_mode: 'mention',
-    engage_pattern: null,
-    sender_scope: 'all',
-    ignored_message_policy: 'drop',
-    session_mode: 'shared',
-    priority: 0,
-    created_at: '2026-05-05T00:00:00Z',
-    mg_channel_type: 'discord',
-    mg_platform_id: 'guild-123',
-    mg_name: 'general',
-    ag_folder: 'research',
-    ag_name: 'Research',
-    ...overrides,
-  };
-}
-
-function baseCurrent(overrides: Partial<MessagingGroupAgent> = {}): MessagingGroupAgent {
-  return {
-    id: 'mga-1',
-    messaging_group_id: 'mg-1',
-    agent_group_id: 'ag-1',
-    engage_mode: 'mention',
-    engage_pattern: null,
-    sender_scope: 'all',
-    ignored_message_policy: 'drop',
-    session_mode: 'shared',
-    priority: 0,
-    created_at: '2026-05-05T00:00:00Z',
-    ...overrides,
-  };
-}
-
-describe('dbToApiEngage', () => {
-  it('mention + null → mention', () => {
-    expect(dbToApiEngage('mention', null)).toBe('mention');
-  });
-
-  it('mention-sticky collapses to mention on the wire', () => {
-    // The wire deliberately doesn't expose sticky — see api-translator.ts
-    // docblock. apiToDbPatch's mention-sticky preservation is what keeps
-    // sticky-mode rows from silently flattening on PATCHes that don't
-    // touch the engagement fields.
-    expect(dbToApiEngage('mention-sticky', null)).toBe('mention');
-  });
-
-  it("pattern + '.' sentinel → all", () => {
-    expect(dbToApiEngage('pattern', ALL_MESSAGES_PATTERN_SENTINEL)).toBe('all');
-  });
-
-  it('pattern + real regex body → pattern', () => {
-    expect(dbToApiEngage('pattern', '\\bdeploy\\b')).toBe('pattern');
-  });
-
-  it('pattern + null → pattern (defensive — schema disallows but translator must not crash)', () => {
-    expect(dbToApiEngage('pattern', null)).toBe('pattern');
-  });
-});
-
-describe('dbToApiSenderScope', () => {
-  it("DB 'known' → wire 'allowlist'", () => {
-    expect(dbToApiSenderScope('known')).toBe('allowlist');
-  });
-
-  it("DB 'all' → wire 'unrestricted' (paraclaw#94 — disjoint literals)", () => {
-    expect(dbToApiSenderScope('all')).toBe('unrestricted');
-  });
-});
-
-describe('dbToApiIgnoredPolicy', () => {
-  it("DB 'accumulate' → wire 'silent'", () => {
-    expect(dbToApiIgnoredPolicy('accumulate')).toBe('silent');
-  });
-
-  it("DB 'drop' → wire 'drop'", () => {
-    expect(dbToApiIgnoredPolicy('drop')).toBe('drop');
-  });
-});
-
-describe('rowToView', () => {
-  it('projects every join column onto the wire view', () => {
-    const view = rowToView(
-      baseRow({
-        engage_mode: 'pattern',
-        engage_pattern: '\\bping\\b',
-        sender_scope: 'known',
-        ignored_message_policy: 'accumulate',
-        priority: 5,
-      }),
-    );
-    expect(view).toEqual({
-      id: 'mga-1',
-      channelType: 'discord',
-      messagingGroupId: 'mg-1',
-      platformId: 'guild-123',
-      displayName: 'general',
-      agentGroupId: 'ag-1',
-      agentGroupFolder: 'research',
-      agentGroupName: 'Research',
-      engageMode: 'pattern',
-      engagePattern: '\\bping\\b',
-      senderScope: 'allowlist',
-      ignoredMessagePolicy: 'silent',
-      priority: 5,
-      createdAt: '2026-05-05T00:00:00Z',
-    });
-  });
-
-  it("collapses pattern + '.' to engageMode='all' and nulls engagePattern on the wire", () => {
-    const view = rowToView(baseRow({ engage_mode: 'pattern', engage_pattern: ALL_MESSAGES_PATTERN_SENTINEL }));
-    expect(view.engageMode).toBe('all');
-    expect(view.engagePattern).toBeNull();
-  });
-
-  it('mention mode never leaks the engage_pattern column to the wire', () => {
-    // In practice the schema keeps engage_pattern null for mention rows, but
-    // the projection must not surface stale pattern bodies if a row drifts.
-    const view = rowToView(baseRow({ engage_mode: 'mention', engage_pattern: 'leftover' }));
-    expect(view.engageMode).toBe('mention');
-    expect(view.engagePattern).toBeNull();
-  });
-});
-
-describe('apiToDbPatch — engageMode encoding', () => {
-  it("engageMode='all' → mode=pattern + pattern='.'", () => {
-    const out = apiToDbPatch({ engageMode: 'all' }, baseCurrent());
-    expect(out.engage_mode).toBe('pattern');
-    expect(out.engage_pattern).toBe(ALL_MESSAGES_PATTERN_SENTINEL);
-  });
-
-  it('engageMode=pattern + engagePattern → both written', () => {
-    const out = apiToDbPatch({ engageMode: 'pattern', engagePattern: '\\bdeploy\\b' }, baseCurrent());
-    expect(out.engage_mode).toBe('pattern');
-    expect(out.engage_pattern).toBe('\\bdeploy\\b');
-  });
-
-  it('engageMode=pattern without engagePattern → only mode set, pattern preserved on the row', () => {
-    // The PATCH-shape semantic: an undefined field means "leave it alone."
-    // The DB-side row already has the prior pattern; we don't overwrite it.
-    const out = apiToDbPatch({ engageMode: 'pattern' }, baseCurrent({ engage_pattern: 'old' }));
-    expect(out.engage_mode).toBe('pattern');
-    expect(out).not.toHaveProperty('engage_pattern');
-  });
-
-  it("engageMode='mention' nulls engage_pattern", () => {
-    const out = apiToDbPatch({ engageMode: 'mention' }, baseCurrent());
-    expect(out.engage_mode).toBe('mention');
-    expect(out.engage_pattern).toBeNull();
-  });
-
-  it("engageMode='mention' preserves mention-sticky when current row is sticky", () => {
-    // Wire doesn't expose sticky → both mention + mention-sticky show as
-    // 'mention' on the read side. A PATCH that flips back to 'mention' on
-    // the wire shouldn't silently demote the sticky bit on the row.
-    const out = apiToDbPatch({ engageMode: 'mention' }, baseCurrent({ engage_mode: 'mention-sticky' }));
-    expect(out.engage_mode).toBe('mention-sticky');
-    expect(out.engage_pattern).toBeNull();
-  });
-
-  it('engagePattern alone (no engageMode) → only pattern body changes', () => {
-    const out = apiToDbPatch({ engagePattern: '\\bnew\\b' }, baseCurrent({ engage_mode: 'pattern' }));
-    expect(out).not.toHaveProperty('engage_mode');
-    expect(out.engage_pattern).toBe('\\bnew\\b');
-  });
-});
-
-describe('apiToDbPatch — sender scope and ignored policy', () => {
-  it("senderScope 'allowlist' → DB 'known'", () => {
-    expect(apiToDbPatch({ senderScope: 'allowlist' }, baseCurrent()).sender_scope).toBe('known');
-  });
-
-  it("senderScope 'unrestricted' → DB 'all'", () => {
-    expect(apiToDbPatch({ senderScope: 'unrestricted' }, baseCurrent()).sender_scope).toBe('all');
-  });
-
-  it("ignoredMessagePolicy 'silent' → DB 'accumulate'", () => {
-    expect(apiToDbPatch({ ignoredMessagePolicy: 'silent' }, baseCurrent()).ignored_message_policy).toBe('accumulate');
-  });
-
-  it("ignoredMessagePolicy 'drop' → DB 'drop'", () => {
-    expect(apiToDbPatch({ ignoredMessagePolicy: 'drop' }, baseCurrent()).ignored_message_policy).toBe('drop');
-  });
-
-  it('priority passes through unchanged', () => {
-    expect(apiToDbPatch({ priority: 7 }, baseCurrent()).priority).toBe(7);
-  });
-
-  it('empty input → empty patch', () => {
-    expect(apiToDbPatch({}, baseCurrent())).toEqual({});
-  });
-});
-
-describe('validatePatchInput', () => {
-  it('rejects non-object body', () => {
-    expect(validatePatchInput(null)).toEqual({ ok: false, reason: 'body must be an object' });
-    expect(validatePatchInput('string')).toEqual({ ok: false, reason: 'body must be an object' });
-    expect(validatePatchInput(42)).toEqual({ ok: false, reason: 'body must be an object' });
-  });
-
-  it('passes a fully-populated valid body', () => {
-    const result = validatePatchInput({
-      engageMode: 'pattern',
-      engagePattern: '\\bping\\b',
-      senderScope: 'allowlist',
-      ignoredMessagePolicy: 'silent',
-      priority: 3,
-    });
-    expect(result).toEqual({
-      ok: true,
-      input: {
-        engageMode: 'pattern',
-        engagePattern: '\\bping\\b',
-        senderScope: 'allowlist',
-        ignoredMessagePolicy: 'silent',
-        priority: 3,
-      },
-    });
-  });
-
-  it("rejects legacy wire-side senderScope='all' (paraclaw#94 rename)", () => {
-    // Pre-paraclaw#94 the wire used 'all' on both axes; the rename to
-    // 'unrestricted' was specifically to make a grep-refactor unable to
-    // conflate the wire and DB unions. The validator must now reject the
-    // old literal.
-    const result = validatePatchInput({ senderScope: 'all' });
-    expect(result.ok).toBe(false);
-    if (!result.ok) expect(result.reason).toContain('senderScope');
-  });
-
-  it("rejects legacy ignoredMessagePolicy='accumulate' on the wire", () => {
-    // 'accumulate' is the DB-side spelling. The wire spelling is 'silent'.
-    const result = validatePatchInput({ ignoredMessagePolicy: 'accumulate' });
-    expect(result.ok).toBe(false);
-    if (!result.ok) expect(result.reason).toContain('ignoredMessagePolicy');
-  });
-
-  it("rejects engageMode='mention-sticky' (DB-only literal)", () => {
-    const result = validatePatchInput({ engageMode: 'mention-sticky' });
-    expect(result.ok).toBe(false);
-    if (!result.ok) expect(result.reason).toContain('engageMode');
-  });
-
-  it("rejects bare '.' as engagePattern (sentinel reservation)", () => {
-    // Storing '.' would silently round-trip back as engageMode='all' on the
-    // next read. The fix landed in paraclaw#122 — keep the regression here.
-    const result = validatePatchInput({ engagePattern: ALL_MESSAGES_PATTERN_SENTINEL });
-    expect(result.ok).toBe(false);
-    if (!result.ok) expect(result.reason).toMatch(/sentinel/);
-  });
-
-  it("accepts escaped literal-dot pattern '\\\\.'", () => {
-    // The error message above tells the caller to escape; that escaped
-    // form must round-trip cleanly.
-    const result = validatePatchInput({ engagePattern: '\\.' });
-    expect(result.ok).toBe(true);
-    if (result.ok) expect(result.input.engagePattern).toBe('\\.');
-  });
-
-  it('accepts engagePattern=null (clear-the-pattern PATCH)', () => {
-    const result = validatePatchInput({ engagePattern: null });
-    expect(result.ok).toBe(true);
-    if (result.ok) expect(result.input.engagePattern).toBeNull();
-  });
-
-  it('rejects non-string non-null engagePattern', () => {
-    expect(validatePatchInput({ engagePattern: 5 }).ok).toBe(false);
-    expect(validatePatchInput({ engagePattern: {} }).ok).toBe(false);
-  });
-
-  it('rejects non-finite priority', () => {
-    expect(validatePatchInput({ priority: Infinity }).ok).toBe(false);
-    expect(validatePatchInput({ priority: NaN }).ok).toBe(false);
-    expect(validatePatchInput({ priority: '5' }).ok).toBe(false);
-  });
-
-  it('drops unknown keys silently (forward-compat)', () => {
-    // The validator only inspects fields it knows; unknown keys aren't an
-    // error, they just don't make it into the typed output.
-    const result = validatePatchInput({ engageMode: 'mention', futureField: 'nope' });
-    expect(result).toEqual({ ok: true, input: { engageMode: 'mention' } });
-  });
-});

package/src/channels/api-translator.ts

@@ -1,214 +0,0 @@
-/**
- * Shared translator between the storage shape (`messaging_group_agents` row,
- * snake_case + legacy enum names) and the API contract that both `/api/channels`
- * and the MCP `*-channel-wire` tools speak.
- *
- * Background. Both surfaces used to maintain their own copy of these types,
- * constants, translators, and the patch validator. The duplication was a
- * structural drift hazard: paraclaw#94 / PR #122 surfaced exactly that class
- * — the rename of wire-side `'all'` → `'unrestricted'` initially landed only
- * the HTTP-side validator and missed the MCP-side silent-no-op. Extracting
- * here makes the drift class structurally impossible: a future enum change
- * touches one file, both surfaces pick it up. paraclaw#123.
- *
- * API contract: engageMode = mention | pattern | all, senderScope = allowlist
- * | unrestricted, ignoredMessagePolicy = drop | silent.
- *
- * DB shape (still pre-rebuild): engage_mode = mention | pattern |
- * mention-sticky (with engage_pattern='.' as the "match every message"
- * sentinel), sender_scope = all | known, ignored_message_policy = drop |
- * accumulate. The translator collapses pattern + '.' into the API's `all`,
- * lossy on mention-sticky (rendered as `mention` to the wire).
- *
- * The validator returns a discriminated result rather than throwing so each
- * caller can pick its own error idiom: HTTP wraps `{ ok: false }` into a
- * 400 + JSON error; MCP throws on `{ ok: false }`.
- */
-import type {
-  EngageMode as DbEngageMode,
-  IgnoredMessagePolicy as DbIgnoredMessagePolicy,
-  MessagingGroupAgent,
-  SenderScope as DbSenderScope,
-} from '../types.js';
-
-export type ApiEngageMode = 'mention' | 'pattern' | 'all';
-export type ApiSenderScope = 'allowlist' | 'unrestricted';
-export type ApiIgnoredMessagePolicy = 'drop' | 'silent';
-
-export const ALL_MESSAGES_PATTERN_SENTINEL = '.';
-
-export const VALID_API_ENGAGE_MODES: ApiEngageMode[] = ['mention', 'pattern', 'all'];
-export const VALID_API_SENDER_SCOPES: ApiSenderScope[] = ['allowlist', 'unrestricted'];
-export const VALID_API_IGNORED_POLICIES: ApiIgnoredMessagePolicy[] = ['drop', 'silent'];
-
-export interface ChannelWireView {
-  id: string;
-  channelType: string;
-  messagingGroupId: string;
-  platformId: string;
-  displayName: string | null;
-  agentGroupId: string;
-  agentGroupFolder: string;
-  agentGroupName: string;
-  engageMode: ApiEngageMode;
-  engagePattern: string | null;
-  senderScope: ApiSenderScope;
-  ignoredMessagePolicy: ApiIgnoredMessagePolicy;
-  priority: number;
-  createdAt: string;
-}
-
-export interface WireJoinRow extends MessagingGroupAgent {
-  mg_channel_type: string;
-  mg_platform_id: string;
-  mg_name: string | null;
-  ag_folder: string;
-  ag_name: string;
-}
-
-export interface PatchInput {
-  engageMode?: ApiEngageMode;
-  engagePattern?: string | null;
-  senderScope?: ApiSenderScope;
-  ignoredMessagePolicy?: ApiIgnoredMessagePolicy;
-  priority?: number;
-}
-
-export interface DbPatch {
-  engage_mode?: DbEngageMode;
-  engage_pattern?: string | null;
-  sender_scope?: DbSenderScope;
-  ignored_message_policy?: DbIgnoredMessagePolicy;
-  priority?: number;
-}
-
-export function dbToApiEngage(mode: DbEngageMode, pattern: string | null): ApiEngageMode {
-  if (mode === 'pattern') {
-    return pattern === ALL_MESSAGES_PATTERN_SENTINEL ? 'all' : 'pattern';
-  }
-  // mention + mention-sticky both render as 'mention' on the wire today.
-  return 'mention';
-}
-
-export function dbToApiSenderScope(s: DbSenderScope): ApiSenderScope {
-  return s === 'known' ? 'allowlist' : 'unrestricted';
-}
-
-export function dbToApiIgnoredPolicy(p: DbIgnoredMessagePolicy): ApiIgnoredMessagePolicy {
-  return p === 'accumulate' ? 'silent' : 'drop';
-}
-
-export function rowToView(row: WireJoinRow): ChannelWireView {
-  return {
-    id: row.id,
-    channelType: row.mg_channel_type,
-    messagingGroupId: row.messaging_group_id,
-    platformId: row.mg_platform_id,
-    displayName: row.mg_name,
-    agentGroupId: row.agent_group_id,
-    agentGroupFolder: row.ag_folder,
-    agentGroupName: row.ag_name,
-    engageMode: dbToApiEngage(row.engage_mode, row.engage_pattern),
-    engagePattern:
-      row.engage_mode === 'pattern' && row.engage_pattern !== ALL_MESSAGES_PATTERN_SENTINEL ? row.engage_pattern : null,
-    senderScope: dbToApiSenderScope(row.sender_scope),
-    ignoredMessagePolicy: dbToApiIgnoredPolicy(row.ignored_message_policy),
-    priority: row.priority,
-    createdAt: row.created_at,
-  };
-}
-
-export function apiToDbPatch(input: PatchInput, current: MessagingGroupAgent): DbPatch {
-  const out: DbPatch = {};
-
-  // engageMode is paired with engagePattern: 'all' encodes as
-  // mode='pattern' + pattern='.', which the router treats as match-every.
-  if (input.engageMode !== undefined) {
-    if (input.engageMode === 'all') {
-      out.engage_mode = 'pattern';
-      out.engage_pattern = ALL_MESSAGES_PATTERN_SENTINEL;
-    } else if (input.engageMode === 'pattern') {
-      out.engage_mode = 'pattern';
-      // Pattern body comes from input.engagePattern when present; otherwise
-      // preserve what's already on the row. validatePatchInput already
-      // rejects bare '.' here so the next read can't silently collapse to
-      // 'all'.
-      if (input.engagePattern !== undefined) {
-        out.engage_pattern = input.engagePattern;
-      }
-    } else if (input.engageMode === 'mention') {
-      // Preserve mention-sticky if that's what's currently on the row;
-      // collapsing it to plain mention here would silently change router
-      // behavior (sticky engagement persists across replies). The wire
-      // doesn't expose sticky → it sees `mention` for both, but a PATCH
-      // that doesn't touch the sticky distinction shouldn't lose it.
-      out.engage_mode = current.engage_mode === 'mention-sticky' ? 'mention-sticky' : 'mention';
-      out.engage_pattern = null;
-    }
-  } else if (input.engagePattern !== undefined) {
-    // pattern body changed without changing the mode.
-    out.engage_pattern = input.engagePattern;
-  }
-
-  if (input.senderScope !== undefined) {
-    // wire 'unrestricted' → DB 'all'. validatePatchInput has already gated
-    // the union to the two known values, so the binary mapping is safe.
-    out.sender_scope = input.senderScope === 'allowlist' ? 'known' : 'all';
-  }
-  if (input.ignoredMessagePolicy !== undefined) {
-    out.ignored_message_policy = input.ignoredMessagePolicy === 'silent' ? 'accumulate' : 'drop';
-  }
-  if (input.priority !== undefined) {
-    out.priority = input.priority;
-  }
-  return out;
-}
-
-export type ValidatePatchResult = { ok: true; input: PatchInput } | { ok: false; reason: string };
-
-export function validatePatchInput(body: unknown): ValidatePatchResult {
-  if (!body || typeof body !== 'object') return { ok: false, reason: 'body must be an object' };
-  const b = body as Record<string, unknown>;
-  const out: PatchInput = {};
-  if ('engageMode' in b) {
-    if (!VALID_API_ENGAGE_MODES.includes(b.engageMode as ApiEngageMode)) {
-      return { ok: false, reason: `invalid engageMode: ${String(b.engageMode)}` };
-    }
-    out.engageMode = b.engageMode as ApiEngageMode;
-  }
-  if ('engagePattern' in b) {
-    if (b.engagePattern !== null && typeof b.engagePattern !== 'string') {
-      return { ok: false, reason: 'engagePattern must be string or null' };
-    }
-    // Bare '.' is the wire-format sentinel for engageMode='all' — accepting
-    // it as a literal pattern would silently round-trip back as 'all' on the
-    // next read and lose the user's intent. Force the caller to disambiguate.
-    if (b.engagePattern === ALL_MESSAGES_PATTERN_SENTINEL) {
-      return {
-        ok: false,
-        reason:
-          "engagePattern '.' is reserved as the 'all' sentinel — use '\\\\.' (escaped) to match a literal dot, or set engageMode to 'all'",
-      };
-    }
-    out.engagePattern = b.engagePattern as string | null;
-  }
-  if ('senderScope' in b) {
-    if (!VALID_API_SENDER_SCOPES.includes(b.senderScope as ApiSenderScope)) {
-      return { ok: false, reason: `invalid senderScope: ${String(b.senderScope)}` };
-    }
-    out.senderScope = b.senderScope as ApiSenderScope;
-  }
-  if ('ignoredMessagePolicy' in b) {
-    if (!VALID_API_IGNORED_POLICIES.includes(b.ignoredMessagePolicy as ApiIgnoredMessagePolicy)) {
-      return { ok: false, reason: `invalid ignoredMessagePolicy: ${String(b.ignoredMessagePolicy)}` };
-    }
-    out.ignoredMessagePolicy = b.ignoredMessagePolicy as ApiIgnoredMessagePolicy;
-  }
-  if ('priority' in b) {
-    if (typeof b.priority !== 'number' || !Number.isFinite(b.priority)) {
-      return { ok: false, reason: 'priority must be a finite number' };
-    }
-    out.priority = b.priority;
-  }
-  return { ok: true, input: out };
-}

package/src/channels/ask-question.ts

@@ -1,46 +0,0 @@
-/**
- * Shared ask_question payload schema + normalization.
- *
- * Producers (host-side approvals, container-side ask_user_question MCP tool)
- * emit an `ask_question` payload. Options may be bare strings for ergonomics,
- * but are normalized here into a consistent shape before delivery, persistence,
- * and rendering.
- */
-
-export interface OptionInput {
-  label: string;
-  selectedLabel?: string;
-  value?: string;
-}
-
-export type RawOption = string | OptionInput;
-
-export interface NormalizedOption {
-  label: string;
-  selectedLabel: string;
-  value: string;
-}
-
-export function normalizeOption(raw: RawOption): NormalizedOption {
-  if (typeof raw === 'string') {
-    return { label: raw, selectedLabel: raw, value: raw };
-  }
-  const label = raw.label;
-  return {
-    label,
-    selectedLabel: raw.selectedLabel ?? label,
-    value: raw.value ?? label,
-  };
-}
-
-export function normalizeOptions(raws: RawOption[]): NormalizedOption[] {
-  return raws.map(normalizeOption);
-}
-
-export interface AskQuestionPayload {
-  type: 'ask_question';
-  questionId: string;
-  title: string;
-  question: string;
-  options: NormalizedOption[];
-}