@hheei/pi-subagents 0.1.2 → 0.2.3

package/dist/markdown.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Transforms plain agent and background task identifiers (e.g. `agent-1`, `bash-1`)
+ * in Markdown prose by wrapping them in inline code backticks, making them visually
+ * distinct in terminal TUI rendering.
+ *
+ * Preserves text inside code blocks, inline code, and URLs intact.
+ */
+export declare function transformSubagentsMarkdown(markdown: string): string;

package/dist/markdown.js

@@ -0,0 +1,21 @@
+/**
+ * Transforms plain agent and background task identifiers (e.g. `agent-1`, `bash-1`)
+ * in Markdown prose by wrapping them in inline code backticks, making them visually
+ * distinct in terminal TUI rendering.
+ *
+ * Preserves text inside code blocks, inline code, and URLs intact.
+ */
+export function transformSubagentsMarkdown(markdown) {
+    if (!/(?:agent|bash)-\d+/.test(markdown))
+        return markdown;
+    // Split by code blocks (```...```) and inline code (`...`) to only transform prose
+    const parts = markdown.split(/(```[\s\S]*?```|`[^`\n]+`)/g);
+    for (let i = 0; i < parts.length; i += 2) {
+        const part = parts[i];
+        if (part !== undefined && /(?:agent|bash)-\d+/.test(part)) {
+            // Match word boundary: agent-N or bash-N not inside markdown link URLs like (http.../agent-1)
+            parts[i] = part.replace(/(?<![`/\w])((?:agent|bash)-\d+)(?![`\w])/g, "`$1`");
+        }
+    }
+    return parts.join("");
+}

package/dist/protocol.d.ts

@@ -2,20 +2,27 @@ import { type Static, Type } from "typebox";
 export declare const DEFAULT_MAX_FRAME_BYTES: number;
 export declare const DEFAULT_MAX_PENDING_REQUESTS = 128;
 export declare const DEFAULT_MAX_BUFFERED_EVENTS = 256;
-export declare const RUNNER_OPERATIONS: readonly ["prompt", "steer", "follow_up", "abort", "get_state", "get_entries", "get_session_stats", "shutdown", "contact_parent", "report_lifecycle", "report_paused", "pause", "cancel_pause", "close_writer", "start_rpc"];
-export type RunnerOperation = (typeof RUNNER_OPERATIONS)[number];
-/** Runner-local event emitted when the Pi child process exits. */
-export declare const RUNNER_EXIT_EVENT: "runner_exit";
-/** Runner-local event emitted when only the RPC writer exited and the runner stayed up. */
-export declare const WRITER_EXIT_EVENT: "writer_exit";
-/** Runner-local event emitted when buffered events had to be dropped. */
-export declare const RUNNER_EVENTS_DROPPED_EVENT: "runner_events_dropped";
-/** Child-branch event: the TUI left the bound session, quit, or was interrupted. */
+/**
+ * Every operation one end of the bridge may ask of the other. The parent drives the child with the
+ * input and state operations; the child returns reports and its Task result as requests, so a
+ * report the parent refuses (a second Task result) is refused to the child that sent it.
+ */
+export declare const BRIDGE_OPERATIONS: readonly ["prompt", "steer", "follow_up", "abort", "get_state", "get_entries", "shutdown", "contact_parent", "task_result"];
+export type BridgeOperation = (typeof BRIDGE_OPERATIONS)[number];
+/** Child-branch event: the child left the bound session, quit, or was interrupted. */
 export declare const CHILD_LIFECYCLE_EVENT: "child_lifecycle";
-/** Runner-to-bridge event: hold the current turn_end until close_writer or cancel. */
-export declare const PAUSE_EVENT: "pause";
-/** Runner-to-bridge event: release a previous pause generation. */
-export declare const CANCEL_PAUSE_EVENT: "cancel_pause";
+/** Child-to-parent event: the task child submitted its final result. */
+/** Child-to-parent event: input arrived in the child, carrying only where it came from. */
+export declare const CHILD_INPUT_EVENT: "child_input";
+export type ChildInputSource = "interactive" | "extension" | "rpc";
+/**
+ * Transport-level failure with a stable code, shared by both ends of the bridge: the parent sees
+ * it when a child call fails, the child sees the code the parent refused a report with.
+ */
+export declare class BridgeError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
 export declare const HelloFrameSchema: Type.TObject<{
     parentSessionId: Type.TString;
     subagentId: Type.TString;
@@ -24,8 +31,7 @@ export declare const HelloFrameSchema: Type.TObject<{
     token: Type.TString;
     version: Type.TLiteral<1>;
     type: Type.TLiteral<"hello">;
-    role: Type.TOptional<Type.TUnion<[Type.TLiteral<"controller">, Type.TLiteral<"reporter">, Type.TLiteral<"recovery">, Type.TLiteral<"bridge">]>>;
-    claimId: Type.TOptional<Type.TString>;
+    role: Type.TOptional<Type.TLiteral<"child">>;
 }>;
 export declare const HelloAckFrameSchema: Type.TObject<{
     version: Type.TLiteral<1>;
@@ -35,10 +41,10 @@ export declare const RequestFrameSchema: Type.TObject<{
     version: Type.TLiteral<1>;
     type: Type.TLiteral<"request">;
     id: Type.TString;
-    operation: Type.TUnion<Type.TLiteral<"steer" | "follow_up" | "contact_parent" | "pause" | "prompt" | "abort" | "get_state" | "get_entries" | "get_session_stats" | "shutdown" | "report_lifecycle" | "report_paused" | "cancel_pause" | "close_writer" | "start_rpc">[]>;
+    operation: Type.TUnion<Type.TLiteral<"contact_parent" | "steer" | "follow_up" | "prompt" | "abort" | "get_state" | "get_entries" | "shutdown" | "task_result">[]>;
     payload: Type.TOptional<Type.TUnknown>;
 }>;
-export declare const RunnerErrorSchema: Type.TObject<{
+export declare const BridgeErrorSchema: Type.TObject<{
     code: Type.TString;
     message: Type.TString;
 }>;
@@ -63,41 +69,15 @@ export declare const EventFrameSchema: Type.TObject<{
     type: Type.TLiteral<"event">;
     event: Type.TUnknown;
 }>;
-export declare const ServerFrameSchema: Type.TUnion<[Type.TObject<{
-    version: Type.TLiteral<1>;
-    type: Type.TLiteral<"hello_ack">;
-}>, Type.TUnion<[Type.TObject<{
-    version: Type.TLiteral<1>;
-    type: Type.TLiteral<"response">;
-    id: Type.TString;
-    ok: Type.TLiteral<true>;
-    data: Type.TOptional<Type.TUnknown>;
-}>, Type.TObject<{
-    version: Type.TLiteral<1>;
-    type: Type.TLiteral<"response">;
-    id: Type.TString;
-    ok: Type.TLiteral<false>;
-    error: Type.TObject<{
-        code: Type.TString;
-        message: Type.TString;
-    }>;
-}>]>, Type.TObject<{
-    version: Type.TLiteral<1>;
-    type: Type.TLiteral<"event">;
-    event: Type.TUnknown;
-}>]>;
 export declare const PromptPayloadSchema: Type.TObject<{
     message: Type.TString;
 }>;
-export declare const GetEntriesPayloadSchema: Type.TObject<{
-    since: Type.TString;
-}>;
 export declare const ContactReportPayloadSchema: Type.TObject<{
     type: Type.TLiteral<"pi_subagent_report">;
     parentSessionId: Type.TString;
     childId: Type.TString;
     runtimeIdentity: Type.TString;
-    reason: Type.TUnion<[Type.TLiteral<"progress_update">, Type.TLiteral<"important_finding">, Type.TLiteral<"need_decision">, Type.TLiteral<"blocked">]>;
+    reason: Type.TOptional<Type.TUnion<[Type.TLiteral<"success">, Type.TLiteral<"blocked">]>>;
     message: Type.TString;
     sessionId: Type.TOptional<Type.TString>;
 }>;
@@ -110,32 +90,33 @@ export declare const ChildLifecyclePayloadSchema: Type.TObject<{
     sessionId: Type.TString;
     message: Type.TOptional<Type.TString>;
 }>;
-export declare const PauseReportPayloadSchema: Type.TObject<{
-    type: Type.TLiteral<"report_paused">;
+/**
+ * Only the source of the input, never its text: the parent needs to know a human used the child,
+ * and the child's conversation stays in the child.
+ */
+export declare const ChildInputPayloadSchema: Type.TObject<{
+    type: Type.TLiteral<"child_input">;
     parentSessionId: Type.TString;
     childId: Type.TString;
     runtimeIdentity: Type.TString;
-    generation: Type.TInteger;
+    source: Type.TUnion<[Type.TLiteral<"interactive">, Type.TLiteral<"extension">, Type.TLiteral<"rpc">]>;
 }>;
 export type HelloFrame = Static<typeof HelloFrameSchema>;
 export type HelloAckFrame = Static<typeof HelloAckFrameSchema>;
 export type RequestFrame = Static<typeof RequestFrameSchema>;
 export type ResponseFrame = Static<typeof ResponseFrameSchema>;
 export type EventFrame = Static<typeof EventFrameSchema>;
-export type ServerFrame = Static<typeof ServerFrameSchema>;
 export type ContactReportPayload = Static<typeof ContactReportPayloadSchema>;
 export type ChildLifecyclePayload = Static<typeof ChildLifecyclePayloadSchema>;
-export type PauseReportPayload = Static<typeof PauseReportPayloadSchema>;
-export declare function isRunnerOperation(value: unknown): value is RunnerOperation;
+export type ChildInputPayload = Static<typeof ChildInputPayloadSchema>;
 export declare function isHelloFrame(value: unknown): value is HelloFrame;
 export declare function isHelloAckFrame(value: unknown): value is HelloAckFrame;
 export declare function isRequestFrame(value: unknown): value is RequestFrame;
 export declare function isContactReportPayload(value: unknown): value is ContactReportPayload;
 export declare function isChildLifecyclePayload(value: unknown): value is ChildLifecyclePayload;
-export declare function isPauseReportPayload(value: unknown): value is PauseReportPayload;
+export declare function isChildInputPayload(value: unknown): value is ChildInputPayload;
 export declare function isResponseFrame(value: unknown): value is ResponseFrame;
 export declare function isEventFrame(value: unknown): value is EventFrame;
-export declare function isServerFrame(value: unknown): value is ServerFrame;
 export declare function successResponse(id: string, data?: unknown): ResponseFrame;
 export declare function failureResponse(id: string, code: string, message: string): ResponseFrame;
 export declare function eventFrame(event: unknown): EventFrame;

package/dist/protocol.js

@@ -4,37 +4,41 @@ import { PROTOCOL_VERSION } from "./domain.js";
 export const DEFAULT_MAX_FRAME_BYTES = 1024 * 1024;
 export const DEFAULT_MAX_PENDING_REQUESTS = 128;
 export const DEFAULT_MAX_BUFFERED_EVENTS = 256;
-export const RUNNER_OPERATIONS = [
+/**
+ * Every operation one end of the bridge may ask of the other. The parent drives the child with the
+ * input and state operations; the child returns reports and its Task result as requests, so a
+ * report the parent refuses (a second Task result) is refused to the child that sent it.
+ */
+export const BRIDGE_OPERATIONS = [
     "prompt",
     "steer",
     "follow_up",
     "abort",
     "get_state",
     "get_entries",
-    "get_session_stats",
     "shutdown",
     "contact_parent",
-    "report_lifecycle",
-    "report_paused",
-    "pause",
-    "cancel_pause",
-    "close_writer",
-    "start_rpc",
+    "task_result",
 ];
-/** Runner-local event emitted when the Pi child process exits. */
-export const RUNNER_EXIT_EVENT = "runner_exit";
-/** Runner-local event emitted when only the RPC writer exited and the runner stayed up. */
-export const WRITER_EXIT_EVENT = "writer_exit";
-/** Runner-local event emitted when buffered events had to be dropped. */
-export const RUNNER_EVENTS_DROPPED_EVENT = "runner_events_dropped";
-/** Child-branch event: the TUI left the bound session, quit, or was interrupted. */
+/** Child-branch event: the child left the bound session, quit, or was interrupted. */
 export const CHILD_LIFECYCLE_EVENT = "child_lifecycle";
-/** Runner-to-bridge event: hold the current turn_end until close_writer or cancel. */
-export const PAUSE_EVENT = "pause";
-/** Runner-to-bridge event: release a previous pause generation. */
-export const CANCEL_PAUSE_EVENT = "cancel_pause";
+/** Child-to-parent event: the task child submitted its final result. */
+/** Child-to-parent event: input arrived in the child, carrying only where it came from. */
+export const CHILD_INPUT_EVENT = "child_input";
+/**
+ * Transport-level failure with a stable code, shared by both ends of the bridge: the parent sees
+ * it when a child call fails, the child sees the code the parent refused a report with.
+ */
+export class BridgeError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "BridgeError";
+        this.code = code;
+    }
+}
 const nonEmptyString = Type.String({ minLength: 1 });
-const operationSchema = Type.Union(RUNNER_OPERATIONS.map((operation) => Type.Literal(operation)));
+const operationSchema = Type.Union(BRIDGE_OPERATIONS.map((operation) => Type.Literal(operation)));
 const identityProperties = {
     parentSessionId: nonEmptyString,
     subagentId: nonEmptyString,
@@ -45,13 +49,7 @@ const identityProperties = {
 export const HelloFrameSchema = Type.Object({
     version: Type.Literal(PROTOCOL_VERSION),
     type: Type.Literal("hello"),
-    role: Type.Optional(Type.Union([
-        Type.Literal("controller"),
-        Type.Literal("reporter"),
-        Type.Literal("recovery"),
-        Type.Literal("bridge"),
-    ])),
-    claimId: Type.Optional(nonEmptyString),
+    role: Type.Optional(Type.Literal("child")),
     ...identityProperties,
 }, { additionalProperties: false });
 export const HelloAckFrameSchema = Type.Object({ version: Type.Literal(PROTOCOL_VERSION), type: Type.Literal("hello_ack") }, { additionalProperties: false });
@@ -62,7 +60,7 @@ export const RequestFrameSchema = Type.Object({
     operation: operationSchema,
     payload: Type.Optional(Type.Unknown()),
 }, { additionalProperties: false });
-export const RunnerErrorSchema = Type.Object({ code: nonEmptyString, message: nonEmptyString }, { additionalProperties: false });
+export const BridgeErrorSchema = Type.Object({ code: nonEmptyString, message: nonEmptyString }, { additionalProperties: false });
 export const ResponseFrameSchema = Type.Union([
     Type.Object({
         version: Type.Literal(PROTOCOL_VERSION),
@@ -76,28 +74,17 @@ export const ResponseFrameSchema = Type.Union([
         type: Type.Literal("response"),
         id: nonEmptyString,
         ok: Type.Literal(false),
-        error: RunnerErrorSchema,
+        error: BridgeErrorSchema,
     }, { additionalProperties: false }),
 ]);
 export const EventFrameSchema = Type.Object({ version: Type.Literal(PROTOCOL_VERSION), type: Type.Literal("event"), event: Type.Unknown() }, { additionalProperties: false });
-export const ServerFrameSchema = Type.Union([
-    HelloAckFrameSchema,
-    ResponseFrameSchema,
-    EventFrameSchema,
-]);
 export const PromptPayloadSchema = Type.Object({ message: nonEmptyString }, { additionalProperties: false });
-export const GetEntriesPayloadSchema = Type.Object({ since: nonEmptyString }, { additionalProperties: false });
 export const ContactReportPayloadSchema = Type.Object({
     type: Type.Literal("pi_subagent_report"),
     parentSessionId: nonEmptyString,
     childId: nonEmptyString,
     runtimeIdentity: nonEmptyString,
-    reason: Type.Union([
-        Type.Literal("progress_update"),
-        Type.Literal("important_finding"),
-        Type.Literal("need_decision"),
-        Type.Literal("blocked"),
-    ]),
+    reason: Type.Optional(Type.Union([Type.Literal("success"), Type.Literal("blocked")])),
     message: nonEmptyString,
     sessionId: Type.Optional(nonEmptyString),
 }, { additionalProperties: false });
@@ -114,16 +101,21 @@ export const ChildLifecyclePayloadSchema = Type.Object({
     sessionId: nonEmptyString,
     message: Type.Optional(Type.String()),
 }, { additionalProperties: false });
-export const PauseReportPayloadSchema = Type.Object({
-    type: Type.Literal("report_paused"),
+/**
+ * Only the source of the input, never its text: the parent needs to know a human used the child,
+ * and the child's conversation stays in the child.
+ */
+export const ChildInputPayloadSchema = Type.Object({
+    type: Type.Literal(CHILD_INPUT_EVENT),
     parentSessionId: nonEmptyString,
     childId: nonEmptyString,
     runtimeIdentity: nonEmptyString,
-    generation: Type.Integer({ minimum: 1 }),
+    source: Type.Union([
+        Type.Literal("interactive"),
+        Type.Literal("extension"),
+        Type.Literal("rpc"),
+    ]),
 }, { additionalProperties: false });
-export function isRunnerOperation(value) {
-    return typeof value === "string" && RUNNER_OPERATIONS.includes(value);
-}
 export function isHelloFrame(value) {
     return Value.Check(HelloFrameSchema, value);
 }
@@ -139,8 +131,8 @@ export function isContactReportPayload(value) {
 export function isChildLifecyclePayload(value) {
     return Value.Check(ChildLifecyclePayloadSchema, value);
 }
-export function isPauseReportPayload(value) {
-    return Value.Check(PauseReportPayloadSchema, value);
+export function isChildInputPayload(value) {
+    return Value.Check(ChildInputPayloadSchema, value);
 }
 export function isResponseFrame(value) {
     return Value.Check(ResponseFrameSchema, value);
@@ -148,9 +140,6 @@ export function isResponseFrame(value) {
 export function isEventFrame(value) {
     return Value.Check(EventFrameSchema, value);
 }
-export function isServerFrame(value) {
-    return Value.Check(ServerFrameSchema, value);
-}
 export function successResponse(id, data) {
     return {
         version: PROTOCOL_VERSION,

package/dist/registry.d.ts

@@ -1,5 +1,5 @@
-import type { RuntimeClaim, SubagentRecord } from "./domain.js";
-export type RegistryErrorCode = "invalid_parent_session" | "corrupt_registry" | "unsupported_version" | "parent_mismatch" | "invalid_record" | "duplicate_child" | "unknown_child" | "stale_revision" | "runtime_mismatch" | "claim_conflict" | "claim_mismatch" | "stopped_child";
+import type { SubagentRecord } from "./domain.js";
+export type RegistryErrorCode = "invalid_parent_session" | "corrupt_registry" | "unsupported_version" | "parent_mismatch" | "invalid_record" | "duplicate_child" | "unknown_child" | "stale_revision" | "runtime_mismatch" | "stopped_child";
 export declare class SubagentRegistryError extends Error {
     readonly code: RegistryErrorCode;
     constructor(code: RegistryErrorCode, message: string);
@@ -22,12 +22,7 @@ export interface SubagentRegistry {
      * already been replaced by a newer one. The registry owns `revision` and
      * `updatedAt`; the updater's values for those fields are ignored.
      */
-    update(id: string, expectedRevision: number, updater: (record: SubagentRecord) => SubagentRecord, expectedRuntimeIdentity?: string, signal?: AbortSignal): Promise<SubagentRecord>;
-    claim(id: string, expectedRevision: number, claim: RuntimeClaim, expectedRuntimeIdentity?: string, expectedClaimId?: string, signal?: AbortSignal): Promise<SubagentRecord>;
-    markClaimRunner(id: string, claimId: string, runnerPid: number, signal?: AbortSignal): Promise<SubagentRecord>;
-    activateClaim(id: string, claimId: string, runnerPid: number, signal?: AbortSignal): Promise<SubagentRecord>;
-    consumeReconnectClaim(id: string, claimId: string, controllerTokenHash: string, signal?: AbortSignal): Promise<SubagentRecord>;
-    releaseClaim(id: string, claimId: string, signal?: AbortSignal): Promise<SubagentRecord>;
+    update(id: string, expectedRevision: number | undefined, updater: (record: SubagentRecord) => SubagentRecord, expectedRuntimeIdentity?: string, signal?: AbortSignal): Promise<SubagentRecord>;
 }
 export interface CreateSubagentRegistryOptions {
     readonly parentSessionId: string;