@pugi/sdk 0.1.0-alpha.3 → 0.1.0-alpha.5

package/dist/subagent-contracts.js

@@ -0,0 +1,230 @@
+/**
+ * Subagent dispatch contracts (Sprint a5.4 — M1 gap remediation D).
+ *
+ * The Pugi CLI's subagent surface is a typed contract between three layers:
+ *   1. The orchestrator (Mira in the brand persona registry; the parent
+ *      engine loop in the actual runtime) decides a SubagentTask.
+ *   2. The CLI dispatcher (apps/pugi-cli/src/core/subagents/dispatcher.ts)
+ *      resolves role to Cyber-Zoo persona, classifies isolation, emits
+ *      lifecycle events, and returns a SubagentResult.
+ *   3. Future M2 worktree + M3 remote-VM implementations swap the dispatch
+ *      backend without changing the contract.
+ *
+ * IMPORTANT: this module does NOT re-declare the persona roster. The
+ * Cyber-Zoo persona identities live in @pugi/personas and are mapped to
+ * roles inside the CLI. The SDK only carries the role + persona-slug pair
+ * on the wire so the cabinet UI can render the brand persona without
+ * shipping the full roster.
+ */
+import { z } from 'zod';
+import { permissionDecisionSchema, permissionModeSchema } from './permission-rules.js';
+/**
+ * Closed enumeration of CLI subagent roles. Mirrors the SubagentRole union
+ * declared in apps/pugi-cli/src/core/agents/registry.ts. Keep both in
+ * lockstep: the CLI dispatcher imports from @pugi/sdk for wire validation
+ * and from the local registry for persona resolution, so adding a role
+ * requires touching both files together.
+ */
+export const subagentRoleSchema = z.enum([
+    'orchestrator',
+    'architect',
+    'coder',
+    'verifier',
+    'reviewer',
+    'researcher',
+    'release',
+    'devops',
+    'design_qa',
+]);
+/**
+ * Isolation classification for a dispatched subagent. M1 ships the first
+ * three tiers; worktree lands in alpha-6 (per-task git worktree for every
+ * write subagent), remote_vm in M3 (dangerous / long-running jobs).
+ *
+ *   - prompt_only:           reasoning/review folded into the parent
+ *                            engine context. No separate filesystem
+ *                            handle; the parent owns every tool call.
+ *                            Mira (orchestrator) uses this at M1.
+ *   - shared_fs_readonly:    read tools are allowed; write/edit/bash
+ *                            classes are denied at the permission layer.
+ *                            Marcus / Vera / Anika get this at M1.
+ *   - shared_fs_serialized:  write tools are allowed but serialized
+ *                            through a coordinator-held lock so two
+ *                            write-subagents never race on the same
+ *                            workspace. Hiroshi / Olivia / Diego / Sofia.
+ *   - worktree:              per-subagent worktree directory (M2,
+ *                            ADR-0057). Writes never touch the primary
+ *                            workspace until merge.
+ *   - remote_vm:             engine VM spawn (M3). Out of scope for the
+ *                            CLI but reserved in the enum so the wire
+ *                            format does not change between milestones.
+ */
+export const subagentIsolationSchema = z.enum([
+    'prompt_only',
+    'shared_fs_readonly',
+    'shared_fs_serialized',
+    'worktree',
+    'remote_vm',
+]);
+/**
+ * Status of a completed subagent dispatch.
+ *   - shipped:   the subagent returned a final answer and any write tools
+ *                it invoked succeeded.
+ *   - blocked:   the subagent stopped because the budget was hit, plan
+ *                mode refused a write, or a permission rule denied a tool
+ *                call.
+ *   - failed:    the subagent crashed or returned a parseable error.
+ *   - cancelled: the parent or operator cancelled the dispatch via the
+ *                abort signal.
+ */
+export const subagentStatusSchema = z.enum(['shipped', 'blocked', 'failed', 'cancelled']);
+/**
+ * Per-dispatch budget. All three limits are optional; the dispatcher
+ * applies its own per-role defaults when a field is missing. Setting a
+ * field tightens the cap; the dispatcher never relaxes a budget.
+ */
+export const subagentBudgetSchema = z.object({
+    tokens: z.number().int().positive().optional(),
+    dollars: z.number().positive().optional(),
+    wallClockMs: z.number().int().positive().optional(),
+});
+/**
+ * Dispatch input. allowedPaths / deniedPaths mirror the per-task shape on
+ * EngineTask so callers that already build engine tasks can promote a
+ * subset of the fields into a subagent dispatch without a second
+ * translation step.
+ */
+export const subagentTaskSchema = z.object({
+    id: z.string().min(1),
+    role: subagentRoleSchema,
+    prompt: z.string().min(1),
+    permissionMode: permissionModeSchema,
+    budget: subagentBudgetSchema.optional(),
+    allowedPaths: z.array(z.string()).optional(),
+    deniedPaths: z.array(z.string()).optional(),
+});
+/**
+ * Dispatch result. personaSlug is the brand persona that owned the
+ * dispatch (from @pugi/personas via the CLI registry); cabinet UI and
+ * audit replay use it to render the persona avatar / hue token without
+ * needing to re-resolve the role.
+ *
+ * permissionDecisions is an OPTIONAL summary of the most important
+ * permission decisions the dispatcher applied or recorded. Full decision
+ * history lives in .pugi/events.jsonl; this field is a convenience pointer
+ * so cabinet UI can render the "Vera was blocked from editing X" line
+ * without re-parsing the events log.
+ */
+export const subagentResultSchema = z.object({
+    taskId: z.string().min(1),
+    role: subagentRoleSchema,
+    personaSlug: z.string().min(1),
+    status: subagentStatusSchema,
+    summary: z.string(),
+    filesChanged: z.array(z.string()),
+    toolCallCount: z.number().int().nonnegative(),
+    tokensIn: z.number().int().nonnegative(),
+    tokensOut: z.number().int().nonnegative(),
+    durationMs: z.number().int().nonnegative(),
+    permissionDecisions: z.array(permissionDecisionSchema).optional(),
+});
+/* ------------------------------------------------------------------ */
+/* Lifecycle events                                                   */
+/* ------------------------------------------------------------------ */
+/**
+ * Emitted once at dispatch start. parentSessionId is the session that owns
+ * the dispatch (typically the CLI's top-level PugiSession.id); future M2
+ * worktree dispatches will introduce a child session id that
+ * cross-references back to the parent.
+ */
+export const subagentSpawnedEventSchema = z.object({
+    type: z.literal('subagent.spawned'),
+    taskId: z.string().min(1),
+    role: subagentRoleSchema,
+    personaSlug: z.string().min(1),
+    parentSessionId: z.string().min(1),
+    isolation: subagentIsolationSchema,
+    timestamp: z.string().datetime(),
+});
+/**
+ * Emitted once per tool call the subagent makes. toolName is the
+ * registered tool slug (read, write, edit, bash, ...). Full argument
+ * payloads stay in the global audit log under tool_call; this event is
+ * the subagent-scoped index so cabinet UI can render the per-persona tool
+ * tree without a second join.
+ */
+export const subagentToolCallEventSchema = z.object({
+    type: z.literal('subagent.tool_call'),
+    taskId: z.string().min(1),
+    role: subagentRoleSchema,
+    personaSlug: z.string().min(1),
+    toolName: z.string().min(1),
+    toolCallId: z.string().min(1),
+    timestamp: z.string().datetime(),
+});
+/**
+ * Emitted once when the subagent reaches a terminal state with status
+ * shipped. The numeric fields mirror the SubagentResult summary so a
+ * downstream consumer can build a cabinet UI activity row from a single
+ * event without joining back to the result envelope.
+ */
+export const subagentCompletedEventSchema = z.object({
+    type: z.literal('subagent.completed'),
+    taskId: z.string().min(1),
+    role: subagentRoleSchema,
+    personaSlug: z.string().min(1),
+    toolCallCount: z.number().int().nonnegative(),
+    tokensIn: z.number().int().nonnegative(),
+    tokensOut: z.number().int().nonnegative(),
+    durationMs: z.number().int().nonnegative(),
+    timestamp: z.string().datetime(),
+});
+/**
+ * Emitted once when the subagent terminates with status blocked. reason is
+ * a short machine-friendly slug (budget_exhausted, plan_mode_refused,
+ * permission_denied, tool_unavailable) so cabinet UI can group blocked
+ * dispatches by cause; detail is a human-readable summary the operator
+ * can act on.
+ */
+export const subagentBlockedEventSchema = z.object({
+    type: z.literal('subagent.blocked'),
+    taskId: z.string().min(1),
+    role: subagentRoleSchema,
+    personaSlug: z.string().min(1),
+    reason: z.enum([
+        'budget_exhausted',
+        'plan_mode_refused',
+        'permission_denied',
+        'tool_unavailable',
+    ]),
+    detail: z.string().min(1),
+    timestamp: z.string().datetime(),
+});
+/**
+ * Emitted once when the subagent terminates with status failed. The error
+ * field is a one-line summary safe to print in the operator console; full
+ * stack traces stay in the global audit log.
+ */
+export const subagentFailedEventSchema = z.object({
+    type: z.literal('subagent.failed'),
+    taskId: z.string().min(1),
+    role: subagentRoleSchema,
+    personaSlug: z.string().min(1),
+    error: z.string().min(1),
+    timestamp: z.string().datetime(),
+});
+/**
+ * Discriminated union of every subagent lifecycle event. Folded into the
+ * broader auditEventSchema in audit-trace.ts; exported here separately so
+ * dispatcher unit tests can validate against just the subagent surface
+ * without pulling the full audit-trace dependency graph through the test
+ * bundle.
+ */
+export const subagentEventSchema = z.discriminatedUnion('type', [
+    subagentSpawnedEventSchema,
+    subagentToolCallEventSchema,
+    subagentCompletedEventSchema,
+    subagentBlockedEventSchema,
+    subagentFailedEventSchema,
+]);
+//# sourceMappingURL=subagent-contracts.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pugi/sdk",
-  "version": "0.1.0-alpha.3",
+  "version": "0.1.0-alpha.5",
   "description": "Pugi CLI contracts shared by the CLI, docs, and Anvil runtime",
   "homepage": "https://pugi.io",
   "repository": {