@threadbase-sh/agent-types 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ronen Mars
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,51 @@
+# @threadbase/agent-types
+
+Shared wire types for the Threadbase multi-agent pipeline.
+
+These types live on the boundary between two processes:
+
+- **tb-multi-agent** — the Temporal worker that runs the orchestrator + turn workflows and the AI-agent activities.
+- **tb-streamer** — the Temporal client that owns the WebSocket connection to the mobile frontend and writes JSONL.
+
+Both processes consume this package so the wire shapes (progress events, signal payloads, session addendum, final-answer flags) stay in sync. There is no runtime code beyond a single frozen `STAGES` array; everything else is type-only.
+
+## How consumers depend on this
+
+Both consumers add this repo as a **git submodule** at a pinned commit, then point their `package.json` at the submodule path via a `file:` dep:
+
+```jsonc
+// tb-multi-agent/packages/agent-types/  ← submodule path
+// tb-streamer/vendor/agent-types/       ← submodule path
+
+"@threadbase/agent-types": "file:packages/agent-types"  // tb-multi-agent
+"@threadbase/agent-types": "file:vendor/agent-types"    // tb-streamer
+```
+
+Bumping the wire contract is a deliberate three-step act:
+
+1. Edit + commit + push here.
+2. In the consuming repo, `git submodule update --remote vendor/agent-types` (or `packages/agent-types`).
+3. Commit the submodule SHA bump in the consuming repo.
+
+This pattern mirrors how `tb-streamer` consumes `@threadbase/scanner` today.
+
+## Why `private: true` in package.json
+
+The package is **source-public** (this repo is public on GitHub) but **not published to npm**. The `private: true` flag prevents accidental `npm publish` runs. The roadmap for going registry-public lives alongside the tb-streamer distribution refactor — both packages move to npm together (Stage 3 in `tb-multi-agent/docs/ROADMAP.md`).
+
+## Stages of distribution maturity
+
+- ~~**Stage 1:** local `file:` dep, sibling-checkout requirement.~~ Retired 2026-06-04.
+- **Stage 2 (current):** standalone GitHub repo, consumed via git submodule. Both consumers pin a SHA.
+- **Stage 3 (planned):** published npm package. See `tb-multi-agent/docs/ROADMAP.md` and the tb-streamer distribution-refactor spec for the broader unification.
+
+## Local development
+
+```bash
+npm install
+npm test       # vitest, 23 tests
+npm run build  # tsc → dist/
+npm run typecheck
+```
+
+The package is self-contained: no runtime deps, only `typescript` + `vitest` as devDeps.

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { STAGES } from './stage';
+export type { Stage } from './stage';
+export type { ProgressEvent, ProgressEventType, AgentOutputPayload, } from './progress';
+export type { ConversationTurn, UserInputSignal, } from './signal';
+export type { SessionStageAddendum } from './session';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AACjC,YAAY,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAErC,YAAY,EACV,aAAa,EACb,iBAAiB,EACjB,kBAAkB,GACnB,MAAM,YAAY,CAAC;AAEpB,YAAY,EACV,gBAAgB,EAChB,eAAe,GAChB,MAAM,UAAU,CAAC;AAElB,YAAY,EAAE,oBAAoB,EAAE,MAAM,WAAW,CAAC"}

package/dist/index.js

@@ -0,0 +1,7 @@
+"use strict";
+// packages/agent-types/src/index.ts
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.STAGES = void 0;
+var stage_1 = require("./stage");
+Object.defineProperty(exports, "STAGES", { enumerable: true, get: function () { return stage_1.STAGES; } });
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA,oCAAoC;;;AAEpC,iCAAiC;AAAxB,+FAAA,MAAM,OAAA"}

package/dist/progress.d.ts

@@ -0,0 +1,56 @@
+import type { Stage } from './stage';
+/**
+ * The three event kinds the worker may emit to tb-streamer over the webhook.
+ *
+ * - stage_transition: the workflow has moved to a new stage. Carries `stage`,
+ *   and `reworkAttempt` when `stage === 'rework'`.
+ * - agent_output: an agent (worker / reviewer / sign-off) has produced an
+ *   output block to surface to the UI as a chat message. Carries an
+ *   `AgentOutputPayload` in `payload`.
+ * - terminal_failure: the turn has failed and will not produce more output.
+ *   Carries a free-form reason in `payload`.
+ */
+export type ProgressEventType = 'stage_transition' | 'agent_output' | 'terminal_failure';
+/**
+ * The envelope worker activities POST to tb-streamer's webhook receiver.
+ *
+ * Identity:
+ * - `sessionId` routes the event to the right WebSocket connection.
+ * - `turnId` groups events that belong to the same user turn.
+ * - `eventId` is the dedupe key. MUST be generated in workflow code via
+ *   `workflow.uuid4()` so it survives Temporal replay — see spec §7.6.
+ * - `seq` is monotonic within a turn for stable ordering.
+ *
+ * Wire compatibility:
+ * - `stage` is typed as `Stage` here (the package owns the enum), but the
+ *   webhook receiver accepts it as `string` for additive compatibility, so
+ *   the server can ship a new stage value without the client needing a
+ *   coordinated release.
+ */
+export interface ProgressEvent {
+    sessionId: string;
+    turnId: string;
+    eventId: string;
+    seq: number;
+    type: ProgressEventType;
+    stage?: Stage;
+    reworkAttempt?: number;
+    timestamp: number;
+    payload?: Record<string, unknown>;
+}
+/**
+ * Payload of an `agent_output` event. Stored in `ProgressEvent.payload`.
+ *
+ * - `content` is the body of the chat block the UI will render.
+ * - `partial` is reserved for a future streaming-token mode; in milestone B
+ *   blocks are always complete on emission, so this is always undefined.
+ * - `reviewerOverruled` is set on the FINAL agent_output when the rework
+ *   cap was hit and the answer is being delivered without reviewer approval.
+ *   See spec §7.4.
+ */
+export interface AgentOutputPayload {
+    content: string;
+    partial?: boolean;
+    reviewerOverruled?: boolean;
+}
+//# sourceMappingURL=progress.d.ts.map

package/dist/progress.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"progress.d.ts","sourceRoot":"","sources":["../src/progress.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAErC;;;;;;;;;;GAUG;AACH,MAAM,MAAM,iBAAiB,GACzB,kBAAkB,GAClB,cAAc,GACd,kBAAkB,CAAC;AAEvB;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,iBAAiB,CAAC;IACxB,KAAK,CAAC,EAAE,KAAK,CAAC;IACd,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B"}

package/dist/progress.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=progress.js.map

package/dist/progress.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"progress.js","sourceRoot":"","sources":["../src/progress.ts"],"names":[],"mappings":""}

package/dist/session.d.ts

@@ -0,0 +1,24 @@
+import type { Stage } from './stage';
+/**
+ * Fields added to tb-streamer's existing session shape (and the
+ * `session_update` WebSocket event) for multi-agent mode.
+ *
+ * Every field is optional so this remains additive — existing mobile clients
+ * that don't know about `stage` keep working; new clients can render
+ * per-stage UI affordances.
+ *
+ * - `stage` widens to `string` on the wire so the worker can ship a new
+ *   stage value before clients are updated. Internally we type it as
+ *   `Stage | string` to keep autocomplete + literal-checking on the
+ *   producer side.
+ * - `stalledSinceMs` is the number of milliseconds the session has been on
+ *   the current stage without progress. The frontend uses it to surface
+ *   "still working…" or to flag a hang.
+ * - `reworkAttempt` is only meaningful when `stage === 'rework'`.
+ */
+export interface SessionStageAddendum {
+    stage?: Stage | string;
+    stalledSinceMs?: number;
+    reworkAttempt?: number;
+}
+//# sourceMappingURL=session.d.ts.map

package/dist/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAErC;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,oBAAoB;IACnC,KAAK,CAAC,EAAE,KAAK,GAAG,MAAM,CAAC;IACvB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB"}

package/dist/session.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=session.js.map

package/dist/session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.js","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":""}

package/dist/signal.d.ts

@@ -0,0 +1,32 @@
+/**
+ * One entry in the conversationHistory snapshot.
+ *
+ * Owned by tb-streamer in milestone B — tb-streamer composes the snapshot from
+ * its existing ConversationCache (SQLite-backed). The shape is mirrored here so
+ * the signal payload has a stable wire type.
+ *
+ * Additional fields (timestamp, metadata, tool calls) may be added without
+ * breaking compatibility: the orchestrator only forwards the snapshot through
+ * to activities, it does not inspect entry shape.
+ */
+export interface ConversationTurn {
+    role: 'user' | 'assistant';
+    content: string;
+}
+/**
+ * Payload sent by tb-streamer with every `userInput` signal to a session's
+ * long-lived orchestrator workflow.
+ *
+ * - `turnId` is allocated by tb-streamer per user message; it is the same
+ *   turn id worn by every progress event the resulting turn emits.
+ * - `prompt` is the user's message text.
+ * - `conversationHistory` is a snapshot tb-streamer composes from its cache.
+ *   It rides in the payload instead of living in workflow state — see
+ *   spec §6.1 for the rationale (option B.1).
+ */
+export interface UserInputSignal {
+    turnId: string;
+    prompt: string;
+    conversationHistory: ConversationTurn[];
+}
+//# sourceMappingURL=signal.d.ts.map

package/dist/signal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"signal.d.ts","sourceRoot":"","sources":["../src/signal.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;GAUG;AACH,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,GAAG,WAAW,CAAC;IAC3B,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,mBAAmB,EAAE,gBAAgB,EAAE,CAAC;CACzC"}

package/dist/signal.js

@@ -0,0 +1,4 @@
+"use strict";
+// packages/agent-types/src/signal.ts
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=signal.js.map

package/dist/signal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"signal.js","sourceRoot":"","sources":["../src/signal.ts"],"names":[],"mappings":";AAAA,qCAAqC"}

package/dist/stage.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The seven stages a turn passes through. Declared as a readonly tuple so the
+ * `Stage` type is the exact union of these literals — `string` on the wire for
+ * additive compatibility, but type-checked internally.
+ */
+export declare const STAGES: readonly ["thinking", "queued", "processing", "review", "rework", "sign-off", "done"];
+export type Stage = (typeof STAGES)[number];
+//# sourceMappingURL=stage.d.ts.map

package/dist/stage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stage.d.ts","sourceRoot":"","sources":["../src/stage.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,eAAO,MAAM,MAAM,uFAQR,CAAC;AAEZ,MAAM,MAAM,KAAK,GAAG,CAAC,OAAO,MAAM,CAAC,CAAC,MAAM,CAAC,CAAC"}

package/dist/stage.js

@@ -0,0 +1,19 @@
+"use strict";
+// packages/agent-types/src/stage.ts
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.STAGES = void 0;
+/**
+ * The seven stages a turn passes through. Declared as a readonly tuple so the
+ * `Stage` type is the exact union of these literals — `string` on the wire for
+ * additive compatibility, but type-checked internally.
+ */
+exports.STAGES = Object.freeze([
+    'thinking',
+    'queued',
+    'processing',
+    'review',
+    'rework',
+    'sign-off',
+    'done',
+]);
+//# sourceMappingURL=stage.js.map

package/dist/stage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stage.js","sourceRoot":"","sources":["../src/stage.ts"],"names":[],"mappings":";AAAA,oCAAoC;;;AAEpC;;;;GAIG;AACU,QAAA,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC;IAClC,UAAU;IACV,QAAQ;IACR,YAAY;IACZ,QAAQ;IACR,QAAQ;IACR,UAAU;IACV,MAAM;CACE,CAAC,CAAC"}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@threadbase-sh/agent-types",
+  "version": "0.1.0",
+  "description": "Shared wire types for the Threadbase multi-agent pipeline (tb-multi-agent ↔ tb-streamer).",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/RonenMars/threadbase-agent-types.git"
+  },
+  "bugs": {
+    "url": "https://github.com/RonenMars/threadbase-agent-types/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": ["dist", "src", "README.md"],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  },
+  "devDependencies": {
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/git": "^10.0.1",
+    "conventional-changelog-conventionalcommits": "^9.3.1",
+    "semantic-release": "^25.0.5",
+    "typescript": "^5.6.0",
+    "vitest": "^2.1.0"
+  }
+}

package/src/index.ts

@@ -0,0 +1,17 @@
+// packages/agent-types/src/index.ts
+
+export { STAGES } from './stage';
+export type { Stage } from './stage';
+
+export type {
+  ProgressEvent,
+  ProgressEventType,
+  AgentOutputPayload,
+} from './progress';
+
+export type {
+  ConversationTurn,
+  UserInputSignal,
+} from './signal';
+
+export type { SessionStageAddendum } from './session';

package/src/progress.ts

@@ -0,0 +1,62 @@
+// packages/agent-types/src/progress.ts
+import type { Stage } from './stage';
+
+/**
+ * The three event kinds the worker may emit to tb-streamer over the webhook.
+ *
+ * - stage_transition: the workflow has moved to a new stage. Carries `stage`,
+ *   and `reworkAttempt` when `stage === 'rework'`.
+ * - agent_output: an agent (worker / reviewer / sign-off) has produced an
+ *   output block to surface to the UI as a chat message. Carries an
+ *   `AgentOutputPayload` in `payload`.
+ * - terminal_failure: the turn has failed and will not produce more output.
+ *   Carries a free-form reason in `payload`.
+ */
+export type ProgressEventType =
+  | 'stage_transition'
+  | 'agent_output'
+  | 'terminal_failure';
+
+/**
+ * The envelope worker activities POST to tb-streamer's webhook receiver.
+ *
+ * Identity:
+ * - `sessionId` routes the event to the right WebSocket connection.
+ * - `turnId` groups events that belong to the same user turn.
+ * - `eventId` is the dedupe key. MUST be generated in workflow code via
+ *   `workflow.uuid4()` so it survives Temporal replay — see spec §7.6.
+ * - `seq` is monotonic within a turn for stable ordering.
+ *
+ * Wire compatibility:
+ * - `stage` is typed as `Stage` here (the package owns the enum), but the
+ *   webhook receiver accepts it as `string` for additive compatibility, so
+ *   the server can ship a new stage value without the client needing a
+ *   coordinated release.
+ */
+export interface ProgressEvent {
+  sessionId: string;
+  turnId: string;
+  eventId: string;
+  seq: number;
+  type: ProgressEventType;
+  stage?: Stage;
+  reworkAttempt?: number;
+  timestamp: number;
+  payload?: Record<string, unknown>;
+}
+
+/**
+ * Payload of an `agent_output` event. Stored in `ProgressEvent.payload`.
+ *
+ * - `content` is the body of the chat block the UI will render.
+ * - `partial` is reserved for a future streaming-token mode; in milestone B
+ *   blocks are always complete on emission, so this is always undefined.
+ * - `reviewerOverruled` is set on the FINAL agent_output when the rework
+ *   cap was hit and the answer is being delivered without reviewer approval.
+ *   See spec §7.4.
+ */
+export interface AgentOutputPayload {
+  content: string;
+  partial?: boolean;
+  reviewerOverruled?: boolean;
+}

package/src/session.ts

@@ -0,0 +1,25 @@
+// packages/agent-types/src/session.ts
+import type { Stage } from './stage';
+
+/**
+ * Fields added to tb-streamer's existing session shape (and the
+ * `session_update` WebSocket event) for multi-agent mode.
+ *
+ * Every field is optional so this remains additive — existing mobile clients
+ * that don't know about `stage` keep working; new clients can render
+ * per-stage UI affordances.
+ *
+ * - `stage` widens to `string` on the wire so the worker can ship a new
+ *   stage value before clients are updated. Internally we type it as
+ *   `Stage | string` to keep autocomplete + literal-checking on the
+ *   producer side.
+ * - `stalledSinceMs` is the number of milliseconds the session has been on
+ *   the current stage without progress. The frontend uses it to surface
+ *   "still working…" or to flag a hang.
+ * - `reworkAttempt` is only meaningful when `stage === 'rework'`.
+ */
+export interface SessionStageAddendum {
+  stage?: Stage | string;
+  stalledSinceMs?: number;
+  reworkAttempt?: number;
+}

package/src/signal.ts

@@ -0,0 +1,34 @@
+// packages/agent-types/src/signal.ts
+
+/**
+ * One entry in the conversationHistory snapshot.
+ *
+ * Owned by tb-streamer in milestone B — tb-streamer composes the snapshot from
+ * its existing ConversationCache (SQLite-backed). The shape is mirrored here so
+ * the signal payload has a stable wire type.
+ *
+ * Additional fields (timestamp, metadata, tool calls) may be added without
+ * breaking compatibility: the orchestrator only forwards the snapshot through
+ * to activities, it does not inspect entry shape.
+ */
+export interface ConversationTurn {
+  role: 'user' | 'assistant';
+  content: string;
+}
+
+/**
+ * Payload sent by tb-streamer with every `userInput` signal to a session's
+ * long-lived orchestrator workflow.
+ *
+ * - `turnId` is allocated by tb-streamer per user message; it is the same
+ *   turn id worn by every progress event the resulting turn emits.
+ * - `prompt` is the user's message text.
+ * - `conversationHistory` is a snapshot tb-streamer composes from its cache.
+ *   It rides in the payload instead of living in workflow state — see
+ *   spec §6.1 for the rationale (option B.1).
+ */
+export interface UserInputSignal {
+  turnId: string;
+  prompt: string;
+  conversationHistory: ConversationTurn[];
+}

package/src/stage.ts

@@ -0,0 +1,18 @@
+// packages/agent-types/src/stage.ts
+
+/**
+ * The seven stages a turn passes through. Declared as a readonly tuple so the
+ * `Stage` type is the exact union of these literals — `string` on the wire for
+ * additive compatibility, but type-checked internally.
+ */
+export const STAGES = Object.freeze([
+  'thinking',
+  'queued',
+  'processing',
+  'review',
+  'rework',
+  'sign-off',
+  'done',
+] as const);
+
+export type Stage = (typeof STAGES)[number];