@hydraharness/harness-subagent 0.1.1-rc.5

package/lib/types/projection-types.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Pure client-safe subagent projection vocabulary.
+ *
+ * @module @hydraharness/harness-subagent/projection-types
+ */
+/** Durable active-turn timing for one descriptor-backed child session. */
+export interface SubagentTimingProjection {
+    /** Milliseconds accumulated across completed turns after the child's own descriptor. */
+    settledMs: number;
+    /** Same-cut bounds of the currently open turn, when one has not reached `turn/end`. */
+    active?: {
+        /** Start of the open turn. */
+        since: number;
+        /** Latest event time folded into this projection cut. */
+        through: number;
+    };
+}
+/**
+ * Durable identity of one descriptor-backed subagent session: lifecycle mode
+ * plus creation label, folded last-wins from `subagent/descriptor` events.
+ * Label strength follows the descriptor schema: a continuable child always
+ * carries one, a one-shot child may omit it.
+ */
+export type SubagentIdentityProjection = {
+    /** A terminal one-shot child. */
+    mode: 'one-shot';
+    /** Optional durable creation label from the child's descriptor. */
+    label?: string;
+    /**
+     * Seq of the `subagent/descriptor` event this identity was folded from.
+     * `seq >= header.seedLength` proves the identity comes from the child's
+     * OWN log suffix — where a descriptor is immutable once appended — and
+     * not from a fork seed's replayed ancestor descriptor.
+     */
+    seq: number;
+} | {
+    /** A resumable conversation. */
+    mode: 'continuable';
+    /** Durable creation label from the child's descriptor. */
+    label: string;
+    /** Seq of the folded descriptor event; see the one-shot arm for the own-suffix proof. */
+    seq: number;
+};
+declare module '@hydraharness/harness-session-projection/types' {
+    interface SessionProjectionMap {
+        /** Active-turn duration for a descriptor-backed subagent session. */
+        subagentTiming: SubagentTimingProjection;
+        /**
+         * Identity of a descriptor-backed subagent session. `null` ⟺ no valid
+         * descriptor (missing, malformed, or unrecognized-version — deliberately
+         * undistinguished). The sentinel is deliberately serializable: a
+         * value pushed over JSON transports must survive `JSON.stringify`
+         * losslessly, where an `undefined` field would be dropped and a stale
+         * identity would survive on the receiving side. The entry itself stays
+         * non-optional.
+         */
+        subagent: SubagentIdentityProjection | null;
+    }
+}
+//# sourceMappingURL=projection-types.d.ts.map

package/lib/types/projection-types.js

@@ -0,0 +1,7 @@
+/**
+ * Pure client-safe subagent projection vocabulary.
+ *
+ * @module @hydraharness/harness-subagent/projection-types
+ */
+export {};
+//# sourceMappingURL=projection-types.js.map

package/lib/types/projection.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Pure session projections for subagent identity (mode/label) and active-turn
+ * duration.
+ *
+ * @module @hydraharness/harness-subagent/projection
+ */
+import { z } from 'zod';
+import type { SessionEvent } from '@hydraharness/harness-session';
+import type { SubagentIdentityProjection, SubagentTimingProjection } from './projection-types.ts';
+/** Fold state for a subagent's latest timing snapshot. */
+export interface TimingState {
+    /** Milliseconds accumulated across completed post-descriptor turns. */
+    settledMs: number;
+    /** Current open interval kept paired inside the fold. */
+    active?: {
+        since: number;
+        through: number;
+    } | undefined;
+    /** Latest pre-descriptor turn start, promoted when the child's own descriptor arrives. */
+    pendingTurnStart?: number | undefined;
+    /** Whether the fold has crossed a descriptor in this logical log. */
+    descriptorSeen: boolean;
+}
+declare module '@hydraharness/harness-session-projection/types' {
+    interface SessionProjectionStateMap {
+        subagentTiming: TimingState;
+        subagent: IdentityState;
+    }
+}
+/**
+ * Fold turn boundaries around the child's own durable descriptor.
+ *
+ * A fork seed may contain an ancestor descriptor and completed turns. Every
+ * descriptor therefore resets the accumulated state; the healthy catalog
+ * admits only a child with exactly one descriptor in its own suffix, making
+ * the final reset the child's authoritative timing origin.
+ */
+export declare const subagentTimingProjectionDefinition: {
+    key: "subagentTiming";
+    stateSchema: z.ZodType<TimingState, unknown, z.core.$ZodTypeInternals<TimingState, unknown>>;
+    init: () => {
+        descriptorSeen: false;
+        settledMs: number;
+    };
+    apply: (state: NoInfer<TimingState>, event: SessionEvent) => {
+        /** Milliseconds accumulated across completed post-descriptor turns. */
+        settledMs: number;
+        /** Current open interval kept paired inside the fold. */
+        active?: {
+            since: number;
+            through: number;
+        } | undefined;
+        /** Whether the fold has crossed a descriptor in this logical log. */
+        descriptorSeen: boolean;
+    };
+    wire: {
+        viewSchema: z.ZodType<SubagentTimingProjection, unknown, z.core.$ZodTypeInternals<SubagentTimingProjection, unknown>>;
+        view: (state: NoInfer<TimingState>) => {
+            active?: {
+                since: number;
+                through: number;
+            };
+            settledMs: number;
+        };
+    };
+    stateVersion: number;
+};
+interface IdentityState {
+    /** Identity from the last valid descriptor; absent before one, and after an invalid one. */
+    identity?: SubagentIdentityProjection | undefined;
+}
+/**
+ * Fold the durable mode/label identity from `subagent/descriptor` events,
+ * last-wins: a fork seed may replay an ancestor's descriptor, and the child's
+ * own descriptor must override it — the same reset discipline as
+ * {@link subagentTimingProjectionDefinition}. A malformed or unknown-version
+ * payload resets to the `null` sentinel instead of throwing, so a fork of a
+ * healthy ancestor never inherits an identity its own descriptor failed to
+ * establish — and the reset survives every JSON push frame, so a consumer
+ * holding the earlier identity replaces it instead of keeping it stale;
+ * `null` ⟺ no valid descriptor, with the causes deliberately undistinguished.
+ */
+export declare const subagentIdentityProjectionDefinition: {
+    key: "subagent";
+    stateSchema: z.ZodType<IdentityState, unknown, z.core.$ZodTypeInternals<IdentityState, unknown>>;
+    init: () => {};
+    apply: (state: NoInfer<IdentityState>, event: SessionEvent) => IdentityState;
+    wire: {
+        viewSchema: z.ZodNullable<z.ZodType<SubagentIdentityProjection, unknown, z.core.$ZodTypeInternals<SubagentIdentityProjection, unknown>>>;
+        view: (state: NoInfer<IdentityState>) => SubagentIdentityProjection | null;
+    };
+    stateVersion: number;
+};
+export {};
+//# sourceMappingURL=projection.d.ts.map

package/lib/types/projection.js

@@ -0,0 +1,150 @@
+/**
+ * Pure session projections for subagent identity (mode/label) and active-turn
+ * duration.
+ *
+ * @module @hydraharness/harness-subagent/projection
+ */
+import { z } from 'zod';
+import { foldSubagentDescriptor } from "./descriptor.js";
+const activeIntervalSchema = z.object({
+    since: z.number().int().nonnegative(),
+    through: z.number().int().nonnegative(),
+}).strict();
+const projectionSchema = z.object({
+    settledMs: z.number().int().nonnegative(),
+    active: activeIntervalSchema.optional(),
+}).strict().transform(({ settledMs, active }) => ({
+    settledMs,
+    ...active === undefined ? {} : { active },
+}));
+const timingStateSchema = z.object({
+    settledMs: z.number().int().nonnegative(),
+    active: activeIntervalSchema.optional(),
+    pendingTurnStart: z.number().int().nonnegative().optional(),
+    descriptorSeen: z.boolean(),
+}).strict();
+/**
+ * Fold turn boundaries around the child's own durable descriptor.
+ *
+ * A fork seed may contain an ancestor descriptor and completed turns. Every
+ * descriptor therefore resets the accumulated state; the healthy catalog
+ * admits only a child with exactly one descriptor in its own suffix, making
+ * the final reset the child's authoritative timing origin.
+ */
+export const subagentTimingProjectionDefinition = {
+    key: 'subagentTiming',
+    stateSchema: timingStateSchema,
+    init: () => ({ descriptorSeen: false, settledMs: 0 }),
+    apply: (state, event) => {
+        if (event.type === 'turn/start') {
+            return state.descriptorSeen
+                ? { ...state, active: { since: event.time, through: event.time } }
+                : { ...state, pendingTurnStart: event.time };
+        }
+        if (event.type === 'subagent/descriptor') {
+            const activeSince = state.active?.since ?? state.pendingTurnStart;
+            return {
+                descriptorSeen: true,
+                settledMs: 0,
+                ...(activeSince === undefined
+                    ? {}
+                    : { active: { since: activeSince, through: event.time } }),
+            };
+        }
+        if (event.type === 'turn/end') {
+            if (!state.descriptorSeen) {
+                if (state.pendingTurnStart === undefined)
+                    return state;
+                const { pendingTurnStart: _closed, ...next } = state;
+                return next;
+            }
+            if (state.active === undefined)
+                return state;
+            const { active, ...rest } = state;
+            return {
+                ...rest,
+                settledMs: state.settledMs + Math.max(0, event.time - active.since),
+            };
+        }
+        if (state.active === undefined)
+            return state;
+        return { ...state, active: { ...state.active, through: event.time } };
+    },
+    wire: {
+        viewSchema: projectionSchema,
+        view: state => ({
+            settledMs: state.settledMs,
+            ...(state.active === undefined ? {} : { active: state.active }),
+        }),
+    },
+    stateVersion: 2,
+};
+// The cast bridges only the optional-label arm: Zod's optional output
+// includes explicit `undefined`, which exactOptionalPropertyTypes excludes
+// from the public interface. The no-value state itself is the serializable
+// `null` arm — never `undefined` — so every registry read and push frame
+// survives JSON.stringify losslessly.
+const identityValueSchema = z.discriminatedUnion('mode', [
+    z.object({
+        mode: z.literal('one-shot'),
+        label: z.string().optional(),
+        seq: z.number().int().nonnegative(),
+    }).strict(),
+    z.object({
+        mode: z.literal('continuable'),
+        label: z.string(),
+        seq: z.number().int().nonnegative(),
+    }).strict(),
+]);
+const identitySchema = identityValueSchema.nullable();
+const identityStateSchema = z.object({
+    identity: identityValueSchema.optional(),
+}).strict();
+/** Interpret one `subagent/descriptor` event's identity; no value when the payload cannot be trusted. */
+function descriptorIdentity(event) {
+    let descriptor;
+    try {
+        descriptor = foldSubagentDescriptor([event]);
+    }
+    catch {
+        // Only a malformed current-version payload throws in descriptor parsing;
+        // a projection fold must never throw, so damage folds to no value.
+        descriptor = undefined;
+    }
+    if (descriptor === undefined)
+        return undefined;
+    return descriptor.mode === 'one-shot'
+        ? {
+            mode: 'one-shot',
+            ...descriptor.label !== undefined ? { label: descriptor.label } : {},
+            seq: event.seq,
+        }
+        : { mode: 'continuable', label: descriptor.label, seq: event.seq };
+}
+/**
+ * Fold the durable mode/label identity from `subagent/descriptor` events,
+ * last-wins: a fork seed may replay an ancestor's descriptor, and the child's
+ * own descriptor must override it — the same reset discipline as
+ * {@link subagentTimingProjectionDefinition}. A malformed or unknown-version
+ * payload resets to the `null` sentinel instead of throwing, so a fork of a
+ * healthy ancestor never inherits an identity its own descriptor failed to
+ * establish — and the reset survives every JSON push frame, so a consumer
+ * holding the earlier identity replaces it instead of keeping it stale;
+ * `null` ⟺ no valid descriptor, with the causes deliberately undistinguished.
+ */
+export const subagentIdentityProjectionDefinition = {
+    key: 'subagent',
+    stateSchema: identityStateSchema,
+    init: () => ({}),
+    apply: (state, event) => {
+        if (event.type !== 'subagent/descriptor')
+            return state;
+        const identity = descriptorIdentity(event);
+        return identity === undefined ? {} : { identity };
+    },
+    wire: { viewSchema: identitySchema, view: state => state.identity ?? null },
+    // Bumped when the identity gained its `seq` field: an older checkpoint row
+    // would replay into a value the schema rejects, so it must refold instead.
+    stateVersion: 2,
+};
+//# sourceMappingURL=projection.js.map

package/lib/types/run-settlement.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Settlement of one ONE-SHOT subagent run into a background-Task outcome. Only
+ * the one-shot background path uses Jobs; continuable children have no Task,
+ * no per-message result, and no Task cancellation.
+ *
+ * @module @hydraharness/harness-subagent/run-settlement
+ */
+import type { JobOutcome } from '@hydraharness/harness-jobs';
+import type { SubagentRun } from './types.ts';
+/**
+ * Await the child result, dispose the run, then return its task outcome. Result
+ * and disposal failures become `failed`; when both fail, both details survive.
+ * @param run - live run to settle and release.
+ * @returns outcome after child resources are released.
+ */
+export declare function settleRun(run: SubagentRun): Promise<JobOutcome>;
+//# sourceMappingURL=run-settlement.d.ts.map

package/lib/types/run-settlement.js

@@ -0,0 +1,66 @@
+/**
+ * Settlement of one ONE-SHOT subagent run into a background-Task outcome. Only
+ * the one-shot background path uses Jobs; continuable children have no Task,
+ * no per-message result, and no Task cancellation.
+ *
+ * @module @hydraharness/harness-subagent/run-settlement
+ */
+/** Flatten a child's final output blocks to the task's final text. */
+function finalText(blocks) {
+    return blocks
+        .filter((block) => block.type === 'text')
+        .map(block => block.text)
+        .join('');
+}
+/** Render a failed stop reason with optional provider-authored detail. */
+function failureDetail(result) {
+    const stopReason = result.stopReason;
+    return result.diagnostic === undefined
+        ? stopReason
+        : `${stopReason}; diagnostic: ${result.diagnostic}`;
+}
+/**
+ * Map a child result to the task outcome: completed carries final text,
+ * aborted is killed, and every other reason is failed without partial output.
+ * @param result - child terminal result.
+ * @returns outcome for the `ctx.jobs` registration.
+ */
+function runOutcome(result) {
+    switch (result.stopReason) {
+        case 'completed':
+            return { status: 'completed', output: finalText(result.output) };
+        case 'aborted':
+            return { status: 'killed' };
+        case 'error':
+        case 'max-tokens':
+        case 'refusal':
+            return { status: 'failed', detail: failureDetail(result) };
+        // Merge-extensible reasons remain failures with provider-authored detail.
+        default:
+            return { status: 'failed', detail: failureDetail(result) };
+    }
+}
+/**
+ * Await the child result, dispose the run, then return its task outcome. Result
+ * and disposal failures become `failed`; when both fail, both details survive.
+ * @param run - live run to settle and release.
+ * @returns outcome after child resources are released.
+ */
+export async function settleRun(run) {
+    let outcome;
+    try {
+        outcome = runOutcome(await run.result);
+    }
+    catch (error) {
+        outcome = { status: 'failed', detail: String(error) };
+    }
+    try {
+        await run.dispose();
+    }
+    catch (error) {
+        const prefix = outcome.detail === undefined ? '' : `${outcome.detail}; `;
+        return { status: 'failed', detail: `${prefix}dispose failed: ${String(error)}` };
+    }
+    return outcome;
+}
+//# sourceMappingURL=run-settlement.js.map