@hydraharness/harness-subagent 0.1.1-rc.5

package/lib/types/types.d.ts

@@ -0,0 +1,315 @@
+/**
+ * The seam's consumer-facing contracts: request, result, and capability types
+ * for {@link SubagentProvider}, plus the `subagent/start` and `subagent/end`
+ * payloads that plugins and hosts observe. Internal control interfaces belong
+ * with their implementation — the lifecycle observer in `./lifecycle.ts`, the
+ * continuation host in `./continuation.ts` — so this module stays the published
+ * surface rather than a bag of everything type-shaped.
+ *
+ * @module @hydraharness/harness-subagent/types
+ */
+import type { Agent, AgentOptions } from '@hydraharness/harness-agent';
+import type { Branded } from '@hydraharness/harness-brand';
+import type { ContentBlock } from '@hydraharness/harness-llm';
+import type { SessionEvent, SessionId } from '@hydraharness/harness-session';
+import type { ObjectJsonSchema, ToolRestriction } from '@hydraharness/harness-tools';
+import type { SubagentDescriptorData } from './descriptor.ts';
+/** Identifies one accepted subagent run across its lifecycle event pair. */
+export type SubagentRunId = Branded<'SubagentRunId'>;
+/**
+ * Brand a string as a {@link SubagentRunId}.
+ * @param id - the raw run id.
+ * @returns the same string, branded.
+ */
+export declare function SubagentRunId(id: string): SubagentRunId;
+/**
+ * Observe-only identifying detail for a published subagent run, carried by
+ * `subagent/start`. One-shot runs and continuable Activation epochs share this
+ * payload, so an observer sees the same vocabulary for both.
+ */
+export interface SubagentRunInfo {
+    /** Unique identity shared with the paired terminal event. */
+    readonly runId: SubagentRunId;
+    /**
+     * Provider name recorded when the child was first created. The provider may
+     * be absent when an accepted one-shot run becomes ready or a persisted
+     * Activation cold-resumes, because neither lifecycle depends on continued
+     * registration.
+     */
+    readonly provider: string;
+    /** The child agent's id. */
+    readonly id: SessionId;
+    /** Snapshot of whether `SubagentRun.localAgent` was present when start fulfilled. */
+    readonly local: boolean;
+}
+/**
+ * Observe-only outcome detail for a settled subagent run, carried by
+ * `subagent/end` and paired with one {@link SubagentRunInfo} by `runId`.
+ */
+export interface SubagentRunEndInfo {
+    /** Unique identity shared with the paired start event. */
+    readonly runId: SubagentRunId;
+    /** The same provider name carried by the paired start event. */
+    readonly provider: string;
+    /** The child agent's id. */
+    readonly id: SessionId;
+    /** Snapshot of whether `SubagentRun.localAgent` was present when start fulfilled. */
+    readonly local: boolean;
+    /** The terminal stop reason. */
+    readonly stopReason: SubagentResult['stopReason'];
+    /**
+     * The child's final assistant output, selected by the same rule as
+     * {@link SubagentResult.output}; absent on infrastructure rejection or when
+     * the child produced none.
+     */
+    readonly lastAssistantMessage?: ContentBlock[];
+}
+/**
+ * Which START-TIME features a provider supports. Checked by the service before delegating to
+ * {@link SubagentProvider.start}: a request that needs a capability the chosen provider lacks
+ * is rejected with a typed error rather than accepted-then-ignored (the "fail loud, no silent
+ * degradation" rule). These flags describe the ONE-SHOT
+ * {@link SubagentProvider.start} path, where the provider composes the child;
+ * continuable children are composed by the continuation manager itself and are
+ * gated by {@link SubagentProvider.prepareContinuable} instead. Each flag
+ * corresponds one-to-one to a {@link SubagentStartRequest} option: `depthLimit`
+ * to `maxDepth`; the other names match.
+ */
+export interface SubagentCapabilities {
+    readonly outputSchema: boolean;
+    readonly depthLimit: boolean;
+    readonly toolFilter: boolean;
+    readonly persona: boolean;
+}
+/**
+ * What a caller asks for when starting a ONE-SHOT subagent. The tool layer
+ * builds this from the model's `{ description, prompt }` plus its own config;
+ * the service validates {@link SubagentCapabilities} against the named provider
+ * and resolves the durable descriptor before dispatching to
+ * {@link SubagentProvider.start}.
+ */
+export interface SubagentStartRequest {
+    /** Optional short display label persisted with a session-backed child. */
+    readonly label?: string;
+    /** Content delivered as the child's user message. */
+    readonly prompt: ContentBlock[];
+    /**
+     * The spawning agent. In-process providers derive workspace, lineage, and
+     * delegation depth from its durable session state. ACP reads only its cwd,
+     * and only when no deployment `cwd` override is configured.
+     */
+    readonly parent: Agent;
+    /**
+     * Cancellation signal from the spawning context (the tool's `exec.signal`).
+     * This is the canonical cancellation channel both before and after startup:
+     * a provider rejects `start()` after cleaning partial resources when it
+     * fires before the run is published, and cancels the published run's
+     * remaining turn work when it fires afterward.
+     */
+    readonly signal: AbortSignal;
+    readonly agentOptions?: AgentOptions;
+    /**
+     * Object-rooted JSON Schema within `assertObjectJsonSchema`'s enforced subset. Start rejects
+     * unsupported schemas or providers without the capability. Data must be plain host-realm JSON;
+     * a successful child returns the matching value as {@link SubagentResult.structured}.
+     */
+    readonly outputSchema?: ObjectJsonSchema;
+    /**
+     * Optional absolute delegation-depth cap for the child being started: its
+     * computed depth must be less than or equal to this non-negative safe
+     * integer. Requires {@link SubagentCapabilities.depthLimit}; rejected at
+     * start otherwise.
+     */
+    readonly maxDepth?: number;
+    /**
+     * Optional child tool scoping. Requires {@link SubagentCapabilities.toolFilter};
+     * rejected at start otherwise. In-process backends apply it as a scoped
+     * `tools.restrict()` in the child's creation window: the named tools vanish
+     * from the child's prompt AND refuse to execute (one visibility), with loud
+     * unknown-name validation.
+     */
+    readonly toolFilter?: ToolRestriction;
+    /**
+     * Optional per-child persona. Requires {@link SubagentCapabilities.persona};
+     * rejected at start otherwise. In-process backends register it as a scoped
+     * `deployment:persona` section on the child, SHADOWING the deployment's
+     * persona for this child alone — same template semantics as the deployment
+     * persona (strict `{{…}}` interpolation against the registered variables).
+     */
+    readonly persona?: string;
+}
+/**
+ * Provider-facing one-shot request after {@link SubagentRuntime.start} resolves
+ * the durable child descriptor.
+ */
+export interface ResolvedSubagentStartRequest extends SubagentStartRequest {
+    /** Detached descriptor a session-backed provider persists in the child log. */
+    readonly descriptor: SubagentDescriptorData;
+}
+/**
+ * What the continuation manager asks a provider for while materializing one
+ * continuable child's FIRST activation. The manager has already reserved the
+ * durable child identity and owns every later operation, so this request
+ * carries only what distinguishes a fresh child from one seeded with parent
+ * history.
+ */
+export interface ContinuableCreateRequest {
+    /** The reserved durable child session id, for provider diagnostics. */
+    readonly sessionId: SessionId;
+    /** The delegating parent agent whose history a seeding provider reads. */
+    readonly parent: Agent;
+    /**
+     * Caller cancellation, which owns preparation only until the manager accepts
+     * the initial prompt into the child's inbox.
+     */
+    readonly signal: AbortSignal;
+}
+/**
+ * A provider's detached contribution to one continuable child's creation. This
+ * is DATA, never a capability: it carries no Agent, `AgentHandle`, prompt
+ * delivery, result, disposal, or resume operation, because the continuation
+ * manager owns the child's whole lifecycle after preparation.
+ */
+export interface ContinuableCreateSpec {
+    /**
+     * Completed-turn prefix of the parent's log to seed the child session with,
+     * or absent for a fresh child. Same durable contract as
+     * `CreateAgentOptions.seed`: contiguous from seq 0, lossless JSON, balanced.
+     */
+    readonly seed?: readonly SessionEvent[];
+}
+/**
+ * Why a subagent run ended. Merge-extensible (a backend may add variants);
+ * consumers branch on the known cases and fall through `default`. The known
+ * cases mirror the harness turn-end vocabulary so the tool layer can map a
+ * non-`completed` result to an `isError` tool result.
+ */
+export interface SubagentStopReasonMap {
+    /** The child finished its turn normally. */
+    completed: 'completed';
+    /** Cancelled through the request signal or disposal. */
+    aborted: 'aborted';
+    /** Model or transport failure. */
+    error: 'error';
+    /** The child hit its token ceiling before finishing. */
+    'max-tokens': 'max-tokens';
+    /** The child declined the task. */
+    refusal: 'refusal';
+}
+/** The union over {@link SubagentStopReasonMap} — widens automatically as backends merge in variants. */
+export type SubagentStopReason = SubagentStopReasonMap[keyof SubagentStopReasonMap];
+/**
+ * The terminal outcome of a subagent run, resolved by {@link SubagentRun.result}.
+ */
+export interface SubagentResult {
+    /**
+     * The child's final assistant output is the content of its last non-empty
+     * assistant message. Empty-content messages, including usage-only messages,
+     * are skipped. Without a non-empty message, the output is its accumulated
+     * assistant text stream, or `[]` when the child produced neither.
+     */
+    readonly output: ContentBlock[];
+    /**
+     * The structured result after a requested `outputSchema` was successfully
+     * satisfied. Requesting a schema does not guarantee presence: a provider can
+     * end with `stopReason: 'error'` when the child fails or finishes without a
+     * valid capture. The structured value is validated against the requested
+     * output schema by the provider; `unknown` here because the seam is
+     * schema-agnostic.
+     */
+    readonly structured?: unknown;
+    /**
+     * Provider-authored, non-assistant failure detail for a non-`completed`
+     * result. Providers keep this text free of tool inputs, file contents,
+     * environment values, credentials, and raw protocol payloads, and limit it
+     * to 4096 UTF-8 bytes. Consumers present it separately from {@link output}.
+     */
+    readonly diagnostic?: string;
+    /** Why the run ended. A non-`completed` reason means `output` may be partial. */
+    readonly stopReason: SubagentStopReason;
+}
+/**
+ * ONE-SHOT child handle returned after publication. Prompt submission, turn
+ * work, and infrastructure faults after that boundary belong to {@link result}.
+ * Consumers await that result and must always {@link dispose} to cancel
+ * remaining work and reach quiescence. A run is one disposable foreground
+ * delegation with one result; continuable conversations have no run — the
+ * continuation manager holds their `AgentHandle` directly and orders every
+ * turn through the child's own inbox.
+ */
+export interface SubagentRun {
+    /**
+     * Parent-scoped run id. For a local run, this MUST equal the published child
+     * session id, whose `parentSession` records `request.parent.session.id`; a
+     * remote provider mints an id unique in the parent namespace.
+     */
+    readonly id: SessionId;
+    /**
+     * The exact published in-process child, or `undefined` for a remote run.
+     * When present, its id is {@link id}; the provider retains no ownership
+     * implication beyond the run's ordinary {@link dispose} contract.
+     */
+    readonly localAgent: Agent | undefined;
+    /**
+     * Resolves with the child's terminal {@link SubagentResult} when the run
+     * settles. Does NOT reject on a child-level failure — a model/transport
+     * failure resolves with `stopReason: 'error'` so the consumer maps it to an
+     * `isError` tool result. Rejects on an infrastructure fault the seam cannot
+     * represent as a stop reason.
+     */
+    readonly result: Promise<SubagentResult>;
+    /**
+     * Cancel remaining work, reach child quiescence, and release resources.
+     * Idempotent.
+     */
+    dispose(): Promise<void>;
+}
+/**
+ * One registered transport for running child agents. Providers are trusted
+ * same-process implementations; callers treat descriptors and returned values
+ * as borrowed immutable data. The service may call one provider concurrently
+ * for distinct children. Providers isolate operation-local mutable state; a
+ * shared capacity controller may delay an operation but must not couple its
+ * settlement or cleanup to a sibling.
+ */
+export interface SubagentProvider {
+    /** Unique registry name (e.g. `spawn`, `fork`, `acp`). */
+    readonly name: string;
+    /** The start-time features this provider supports (see {@link SubagentCapabilities}). */
+    readonly capabilities: SubagentCapabilities;
+    /**
+     * Whether the child sees the parent's completed-turn prefix. This is descriptive, not a
+     * service-validated start capability: the model-facing tool derives truthful wording from it.
+     * It says nothing about tool registration, injected services, or authority inheritance.
+     */
+    readonly inheritsParentContext: boolean;
+    /**
+     * Establish a ONE-SHOT child and return its handle after publication.
+     * The service has already validated that every requested start-time
+     * capability is supported and resolved `request.descriptor`, so a
+     * session-backed implementation appends that descriptor inside the child's
+     * initial turn. Before fulfillment, the provider owns setup and cleans any
+     * unpublished partial resources before rejecting. Ownership transfers on
+     * fulfillment; subsequent turn or infrastructure failure settles through
+     * the returned run. Distinct starts may overlap; cancellation, failure,
+     * result settlement, and disposal remain independent for each run.
+     */
+    start(request: ResolvedSubagentStartRequest): Promise<SubagentRun>;
+    /**
+     * OPTIONAL (continuable-creation capability): contribute the detached
+     * creation inputs that distinguish this provider's continuable children —
+     * only whether the child session is seeded with parent history. Method
+     * presence IS the capability: the service rejects continuable starts on
+     * providers without it, while a provider that has it may still serve
+     * ordinary one-shot delegations.
+     *
+     * This is the provider's ONLY participation in a continuable child. The
+     * continuation manager owns identity reservation, composition, Agent
+     * creation, prompt delivery, cold resume, ownership, and disposal, so a
+     * provider never sees the child's Agent, handle, turns, or teardown.
+     * Distinct preparations may overlap; each follows its own signal and returns
+     * data belonging only to `request.sessionId`.
+     */
+    prepareContinuable?(request: ContinuableCreateRequest): Promise<ContinuableCreateSpec>;
+}
+//# sourceMappingURL=types.d.ts.map

package/lib/types/types.js

@@ -0,0 +1,19 @@
+/**
+ * The seam's consumer-facing contracts: request, result, and capability types
+ * for {@link SubagentProvider}, plus the `subagent/start` and `subagent/end`
+ * payloads that plugins and hosts observe. Internal control interfaces belong
+ * with their implementation — the lifecycle observer in `./lifecycle.ts`, the
+ * continuation host in `./continuation.ts` — so this module stays the published
+ * surface rather than a bag of everything type-shaped.
+ *
+ * @module @hydraharness/harness-subagent/types
+ */
+/**
+ * Brand a string as a {@link SubagentRunId}.
+ * @param id - the raw run id.
+ * @returns the same string, branded.
+ */
+export function SubagentRunId(id) {
+    return id;
+}
+//# sourceMappingURL=types.js.map

package/package.json

@@ -0,0 +1,112 @@
+{
+  "name": "@hydraharness/harness-subagent",
+  "description": "Abstract subagent seam (ctx.subagents): named-provider registry for delegating to child agents",
+  "hydra": {
+    "plugin": {
+      "application": "Delegate work to registered child-agent providers and track their continuations."
+    }
+  },
+  "version": "0.1.1-rc.5",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MaiHongPhong1902/Hydra-Harness.git",
+    "directory": "packages/subagent/subagent"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./client": {
+      "types": "./lib/types/client.d.ts",
+      "default": "./lib/types/client.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "zod": "^4.4.3",
+    "@hydraharness/schemastery": "^3.18.2"
+  },
+  "peerDependencies": {
+    "@hydraharness/harness-agent": "^0.1.1-rc.5",
+    "@hydraharness/harness-brand": "^0.1.1-rc.5",
+    "@hydraharness/harness-agent-presets": "^0.1.1-rc.5",
+    "@hydraharness/harness-invariants": "^0.1.1-rc.5",
+    "@hydraharness/harness-llm": "^0.1.1-rc.5",
+    "@hydraharness/harness-sandbox-policy": "^0.1.1-rc.5",
+    "@hydraharness/harness-scope": "^0.1.1-rc.5",
+    "@hydraharness/harness-session": "^0.1.1-rc.5",
+    "@hydraharness/harness-session-persistence": "^0.1.1-rc.5",
+    "@hydraharness/harness-session-projection": "^0.1.1-rc.5",
+    "@hydraharness/harness-session-projection-cache": "^0.1.1-rc.5",
+    "@hydraharness/harness-tools": "^0.1.1-rc.5",
+    "@hydraharness/harness-jobs": "^0.1.1-rc.5",
+    "@hydraharness/harness-sandbox": "^0.1.1-rc.5",
+    "@hydraharness/cordis": "^4.0.2",
+    "@hydraharness/harness-user-approval": "^0.1.1-rc.5"
+  },
+  "peerDependenciesMeta": {
+    "@hydraharness/harness-agent-presets": {
+      "optional": true
+    },
+    "@hydraharness/harness-sandbox": {
+      "optional": true
+    },
+    "@hydraharness/harness-sandbox-policy": {
+      "optional": true
+    },
+    "@hydraharness/harness-session-persistence": {
+      "optional": true
+    },
+    "@hydraharness/harness-session-projection": {
+      "optional": true
+    },
+    "@hydraharness/harness-session-projection-cache": {
+      "optional": true
+    },
+    "@hydraharness/harness-jobs": {
+      "optional": true
+    },
+    "@hydraharness/harness-user-approval": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@hydraharness/harness-agent": "^0.1.1-rc.5",
+    "@hydraharness/harness-llm": "^0.1.1-rc.5",
+    "@hydraharness/harness-brand": "^0.1.1-rc.5",
+    "@hydraharness/harness-invariants": "^0.1.1-rc.5",
+    "@hydraharness/harness-agent-presets": "^0.1.1-rc.5",
+    "@hydraharness/harness-sandbox": "^0.1.1-rc.5",
+    "@hydraharness/harness-sandbox-policy": "^0.1.1-rc.5",
+    "@hydraharness/harness-scope": "^0.1.1-rc.5",
+    "@hydraharness/harness-session": "^0.1.1-rc.5",
+    "@hydraharness/harness-session-persistence": "^0.1.1-rc.5",
+    "@hydraharness/harness-session-projection-cache": "^0.1.1-rc.5",
+    "@hydraharness/harness-storage": "^0.1.1-rc.5",
+    "@hydraharness/harness-storage-domain": "^0.1.1-rc.5",
+    "@hydraharness/harness-jobs": "^0.1.1-rc.5",
+    "@hydraharness/harness-session-projection": "^0.1.1-rc.5",
+    "@hydraharness/harness-tools": "^0.1.1-rc.5",
+    "@hydraharness/harness-user-approval": "^0.1.1-rc.5",
+    "@hydraharness/cordis": "^4.0.2"
+  }
+}