@agent-plan/core 0.4.1 → 0.4.2

package/dist/api-v1.d.ts

@@ -0,0 +1,194 @@
+/**
+ * Agent Plan API v1 — the contract for programs outside Agent Plan.
+ *
+ * The stored schemas (schema.ts) are internal and change freely. The views in
+ * this file are what outside programs are promised: every field is picked by
+ * name, so a stored-schema change can never leak into the contract. Adding a
+ * field keeps `API_V1_VERSION`; removing or renaming one, or changing what it
+ * means, needs a new version (see docs/api-v1.md).
+ *
+ * Harness-agnostic: no server, Pi or MCP imports. The HTTP routes, the change
+ * events and any other adapter build on these same mappers.
+ */
+import type { AcceptedDecision, Feature, Idea, Phase, Project, Task } from "./schema.js";
+export declare const API_V1_VERSION = "1";
+export interface ApiV1Envelope<T> {
+    apiVersion: typeof API_V1_VERSION;
+    data: T;
+}
+export interface ApiV1ErrorEnvelope {
+    apiVersion: typeof API_V1_VERSION;
+    error: {
+        code: string;
+        message: string;
+    };
+}
+export declare function apiV1Envelope<T>(data: T): ApiV1Envelope<T>;
+export declare function apiV1Error(code: string, message: string): ApiV1ErrorEnvelope;
+export type ApiV1EntityKind = "project" | "feature" | "phase" | "task" | "decision" | "handoff" | "idea";
+export interface ApiV1Project {
+    name: string;
+    description: string;
+    goal: string;
+    guidelines: string;
+    guidelinesUpdatedAt: string;
+    scope: string[];
+    outOfScope: string[];
+    technologies: string[];
+    tools: string[];
+    contentLanguage: string;
+    chatLanguage: string;
+}
+export interface ApiV1Feature {
+    id: string;
+    ref: string;
+    shortId: string;
+    number: number;
+    name: string;
+    description: string;
+    status: string;
+    priority: number;
+    startDate: string;
+    endDate: string;
+    workDone: string;
+    workRemaining: string;
+    phaseRefs: string[];
+    dependsOn: string[];
+    createdAt: string;
+    updatedAt: string;
+}
+export interface ApiV1Phase {
+    id: string;
+    ref: string;
+    shortId: string;
+    number: number;
+    featureRef: string | null;
+    title: string;
+    summary: string;
+    description: string;
+    status: string;
+    priority: number;
+    goals: string[];
+    dependsOn: string[];
+    taskRefs: string[];
+    hasHandoff: boolean;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface ApiV1ChecklistItem {
+    id: string;
+    number: number;
+    title: string;
+    checked: boolean;
+}
+export interface ApiV1TaskPause {
+    reason: string;
+    resumeLocation: string;
+    pausedAt: string;
+}
+export interface ApiV1Task {
+    id: string;
+    ref: string;
+    shortId: string;
+    number: number;
+    phaseRef: string;
+    featureRef: string | null;
+    title: string;
+    description: string;
+    status: string;
+    priority: number;
+    checklist: ApiV1ChecklistItem[];
+    dependsOn: string[];
+    pause: ApiV1TaskPause | null;
+    startedAt: string;
+    completedAt: string;
+    createdAt: string;
+    updatedAt: string;
+}
+export type ApiV1DecisionOwnerKind = "project" | "feature" | "phase" | "task";
+export interface ApiV1AcceptedDecision {
+    id: string;
+    ref: string;
+    title: string;
+    decision: string;
+    rationale: string;
+    implementationNotes: string;
+    acceptedAt: string;
+    owner: {
+        kind: ApiV1DecisionOwnerKind;
+        ref: string | null;
+    };
+}
+export interface ApiV1Handoff {
+    phaseRef: string;
+    content: string;
+    updatedAt: string;
+    resumeReady: boolean;
+    resumeReadyAt: string;
+}
+export interface ApiV1Idea {
+    id: string;
+    ref: string;
+    shortId: string;
+    number: number;
+    title: string;
+    description: string;
+    promotion: {
+        targetType: string;
+        targetRef: string;
+        promotedAt: string;
+    } | null;
+    createdAt: string;
+    updatedAt: string;
+}
+/** Refs for every entity that other entities point at, built once per model. */
+export interface ApiV1RefContext {
+    featureRefById: ReadonlyMap<string, string>;
+    phaseRefById: ReadonlyMap<string, string>;
+    taskRefById: ReadonlyMap<string, string>;
+}
+export interface ApiV1Source {
+    project: Project;
+    features: readonly Feature[];
+    phases: readonly Phase[];
+    ideas: readonly Idea[];
+}
+export interface ApiV1Model {
+    project: ApiV1Project;
+    features: ApiV1Feature[];
+    phases: ApiV1Phase[];
+    tasks: ApiV1Task[];
+    decisions: ApiV1AcceptedDecision[];
+    handoffs: ApiV1Handoff[];
+    ideas: ApiV1Idea[];
+}
+export declare function formatTaskRef(phaseRef: string, taskNumber: number): string;
+export declare function buildApiV1RefContext(features: readonly Feature[], phases: readonly Phase[]): ApiV1RefContext;
+export declare function toApiV1Project(project: Project): ApiV1Project;
+export declare function toApiV1Feature(feature: Feature, context: ApiV1RefContext): ApiV1Feature;
+export declare function toApiV1Phase(phase: Phase, context: ApiV1RefContext): ApiV1Phase;
+export declare function toApiV1Task(task: Task, phase: Phase, context: ApiV1RefContext): ApiV1Task;
+export declare function toApiV1Decision(decision: AcceptedDecision, owner: {
+    kind: ApiV1DecisionOwnerKind;
+    ref: string | null;
+}): ApiV1AcceptedDecision;
+/** The active handoff of a phase, or null when it has none (or the phase is finished). */
+export declare function toApiV1Handoff(phase: Phase, context: ApiV1RefContext): ApiV1Handoff | null;
+export declare function toApiV1Idea(idea: Idea): ApiV1Idea;
+/** Every view of a loaded planner, with all cross-references turned into human refs. */
+export declare function buildApiV1Model(source: ApiV1Source): ApiV1Model;
+/** One entry per entity, with its parents, for change detection and indexes. */
+export interface ApiV1EntityEntry {
+    kind: ApiV1EntityKind;
+    /** Unique within its kind. Decisions repeat ids across owners, so theirs includes the owner. */
+    key: string;
+    id: string;
+    ref: string;
+    parents: {
+        featureRef?: string;
+        phaseRef?: string;
+    };
+    view: unknown;
+}
+export declare function listApiV1Entities(model: ApiV1Model): ApiV1EntityEntry[];
+//# sourceMappingURL=api-v1.d.ts.map

package/dist/api-v1.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-v1.d.ts","sourceRoot":"","sources":["../src/api-v1.ts"],"names":[],"mappings":"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"}

package/dist/api-v1.js

@@ -0,0 +1,231 @@
+/**
+ * Agent Plan API v1 — the contract for programs outside Agent Plan.
+ *
+ * The stored schemas (schema.ts) are internal and change freely. The views in
+ * this file are what outside programs are promised: every field is picked by
+ * name, so a stored-schema change can never leak into the contract. Adding a
+ * field keeps `API_V1_VERSION`; removing or renaming one, or changing what it
+ * means, needs a new version (see docs/api-v1.md).
+ *
+ * Harness-agnostic: no server, Pi or MCP imports. The HTTP routes, the change
+ * events and any other adapter build on these same mappers.
+ */
+import { formatFeatureRef, formatIdeaRef, formatPhaseRef, formatThreeDigitNumber } from "./naming.js";
+export const API_V1_VERSION = "1";
+export function apiV1Envelope(data) {
+    return { apiVersion: API_V1_VERSION, data };
+}
+export function apiV1Error(code, message) {
+    return { apiVersion: API_V1_VERSION, error: { code, message } };
+}
+/** A phase in one of these statuses has no active handoff (it is archived). */
+const TERMINAL_PHASE_STATUSES = new Set(["done", "canceled", "rejected"]);
+export function formatTaskRef(phaseRef, taskNumber) {
+    return `${phaseRef}/T${formatThreeDigitNumber(taskNumber)}`;
+}
+export function buildApiV1RefContext(features, phases) {
+    const featureNumberById = new Map(features.map((feature) => [feature.id, feature.number]));
+    const featureRefById = new Map(features.map((feature) => [feature.id, formatFeatureRef(feature.number)]));
+    const phaseRefById = new Map();
+    const taskRefById = new Map();
+    for (const phase of phases) {
+        const featureNumber = phase.featureId ? featureNumberById.get(phase.featureId) : undefined;
+        const phaseRef = formatPhaseRef(phase.number, featureNumber);
+        phaseRefById.set(phase.id, phaseRef);
+        for (const task of phase.tasks)
+            taskRefById.set(task.id, formatTaskRef(phaseRef, task.number));
+    }
+    return { featureRefById, phaseRefById, taskRefById };
+}
+/** A dependency that no longer resolves keeps its stored id rather than vanishing. */
+function refsOf(ids, refById) {
+    return ids.map((id) => refById.get(id) ?? id);
+}
+export function toApiV1Project(project) {
+    return {
+        name: project.name,
+        description: project.description,
+        goal: project.goal,
+        guidelines: project.projectGuidelines.content,
+        guidelinesUpdatedAt: project.projectGuidelines.updatedAt,
+        scope: [...project.scope],
+        outOfScope: [...project.outOfScope],
+        technologies: [...project.technologies],
+        tools: [...project.tools],
+        contentLanguage: project.contentLanguage,
+        chatLanguage: project.chatLanguage,
+    };
+}
+export function toApiV1Feature(feature, context) {
+    return {
+        id: feature.id,
+        ref: formatFeatureRef(feature.number),
+        shortId: feature.shortId,
+        number: feature.number,
+        name: feature.name,
+        description: feature.description,
+        status: feature.status,
+        priority: feature.priority,
+        startDate: feature.startDate,
+        endDate: feature.endDate,
+        workDone: feature.workDone,
+        workRemaining: feature.workRemaining,
+        phaseRefs: refsOf(feature.phaseIds, context.phaseRefById),
+        dependsOn: refsOf(feature.dependsOn, context.featureRefById),
+        createdAt: feature.createdAt,
+        updatedAt: feature.updatedAt,
+    };
+}
+export function toApiV1Phase(phase, context) {
+    return {
+        id: phase.id,
+        ref: context.phaseRefById.get(phase.id) ?? formatPhaseRef(phase.number),
+        shortId: phase.shortId,
+        number: phase.number,
+        featureRef: phase.featureId ? context.featureRefById.get(phase.featureId) ?? null : null,
+        title: phase.title,
+        summary: phase.summary,
+        description: phase.description,
+        status: phase.status,
+        priority: phase.priority,
+        goals: [...phase.goals],
+        dependsOn: refsOf(phase.dependsOn, context.phaseRefById),
+        taskRefs: phase.tasks.map((task) => context.taskRefById.get(task.id) ?? task.id),
+        hasHandoff: hasActiveHandoff(phase),
+        createdAt: phase.createdAt,
+        updatedAt: phase.updatedAt,
+    };
+}
+export function toApiV1Task(task, phase, context) {
+    return {
+        id: task.id,
+        ref: context.taskRefById.get(task.id) ?? formatTaskRef(formatPhaseRef(phase.number), task.number),
+        shortId: task.shortId,
+        number: task.number,
+        phaseRef: context.phaseRefById.get(phase.id) ?? formatPhaseRef(phase.number),
+        featureRef: phase.featureId ? context.featureRefById.get(phase.featureId) ?? null : null,
+        title: task.title,
+        description: task.description,
+        status: task.status,
+        priority: task.priority,
+        checklist: task.checklist.map((item) => {
+            // The schema transform always expands string items into objects.
+            const entry = typeof item === "string" ? { id: item, number: 0, title: item, checked: false } : item;
+            return { id: entry.id, number: entry.number, title: entry.title, checked: entry.checked };
+        }),
+        dependsOn: refsOf(task.dependsOn, context.taskRefById),
+        pause: task.pauseSnapshot
+            ? { reason: task.pauseSnapshot.reason, resumeLocation: task.pauseSnapshot.resumeLocation, pausedAt: task.pauseSnapshot.pausedAt }
+            : null,
+        startedAt: task.startedAt,
+        completedAt: task.completedAt,
+        createdAt: task.createdAt,
+        updatedAt: task.updatedAt,
+    };
+}
+export function toApiV1Decision(decision, owner) {
+    return {
+        id: decision.id,
+        ref: `${owner.ref ?? "project"}#${decision.id}`,
+        title: decision.title,
+        decision: decision.decision,
+        rationale: decision.rationale,
+        implementationNotes: decision.implementationNotes,
+        acceptedAt: decision.acceptedAt,
+        owner: { kind: owner.kind, ref: owner.ref },
+    };
+}
+function hasActiveHandoff(phase) {
+    return phase.handoff.length > 0 && !TERMINAL_PHASE_STATUSES.has(phase.status);
+}
+/** The active handoff of a phase, or null when it has none (or the phase is finished). */
+export function toApiV1Handoff(phase, context) {
+    if (!hasActiveHandoff(phase))
+        return null;
+    const resumeReadyAt = phase.handoffAudit?.resumeReadyAt ?? "";
+    return {
+        phaseRef: context.phaseRefById.get(phase.id) ?? formatPhaseRef(phase.number),
+        content: phase.handoff,
+        updatedAt: phase.handoffUpdatedAt || phase.updatedAt,
+        resumeReady: resumeReadyAt !== "",
+        resumeReadyAt,
+    };
+}
+export function toApiV1Idea(idea) {
+    return {
+        id: idea.id,
+        ref: formatIdeaRef(idea.number),
+        shortId: idea.shortId,
+        number: idea.number,
+        title: idea.title,
+        description: idea.description,
+        promotion: idea.promotion
+            ? { targetType: idea.promotion.targetType, targetRef: idea.promotion.targetRef, promotedAt: idea.promotion.promotedAt }
+            : null,
+        createdAt: idea.createdAt,
+        updatedAt: idea.updatedAt,
+    };
+}
+/** Every view of a loaded planner, with all cross-references turned into human refs. */
+export function buildApiV1Model(source) {
+    const context = buildApiV1RefContext(source.features, source.phases);
+    const decisions = source.project.acceptedDecisions.map((decision) => toApiV1Decision(decision, { kind: "project", ref: null }));
+    for (const feature of source.features) {
+        const owner = { kind: "feature", ref: formatFeatureRef(feature.number) };
+        for (const decision of feature.acceptedDecisions)
+            decisions.push(toApiV1Decision(decision, owner));
+    }
+    const tasks = [];
+    const handoffs = [];
+    for (const phase of source.phases) {
+        const phaseRef = context.phaseRefById.get(phase.id) ?? formatPhaseRef(phase.number);
+        for (const decision of phase.acceptedDecisions)
+            decisions.push(toApiV1Decision(decision, { kind: "phase", ref: phaseRef }));
+        const handoff = toApiV1Handoff(phase, context);
+        if (handoff)
+            handoffs.push(handoff);
+        for (const task of phase.tasks) {
+            tasks.push(toApiV1Task(task, phase, context));
+            const taskRef = context.taskRefById.get(task.id) ?? task.id;
+            for (const decision of task.acceptedDecisions)
+                decisions.push(toApiV1Decision(decision, { kind: "task", ref: taskRef }));
+        }
+    }
+    return {
+        project: toApiV1Project(source.project),
+        features: source.features.map((feature) => toApiV1Feature(feature, context)),
+        phases: source.phases.map((phase) => toApiV1Phase(phase, context)),
+        tasks,
+        decisions,
+        handoffs,
+        ideas: source.ideas.map(toApiV1Idea),
+    };
+}
+export function listApiV1Entities(model) {
+    const entries = [
+        { kind: "project", key: "project", id: "project", ref: "project", parents: {}, view: model.project },
+    ];
+    for (const feature of model.features) {
+        entries.push({ kind: "feature", key: feature.id, id: feature.id, ref: feature.ref, parents: {}, view: feature });
+    }
+    for (const phase of model.phases) {
+        entries.push({ kind: "phase", key: phase.id, id: phase.id, ref: phase.ref, parents: phase.featureRef ? { featureRef: phase.featureRef } : {}, view: phase });
+    }
+    for (const task of model.tasks) {
+        entries.push({
+            kind: "task", key: task.id, id: task.id, ref: task.ref,
+            parents: { ...(task.featureRef ? { featureRef: task.featureRef } : {}), phaseRef: task.phaseRef },
+            view: task,
+        });
+    }
+    for (const decision of model.decisions) {
+        entries.push({ kind: "decision", key: decision.ref, id: decision.id, ref: decision.ref, parents: {}, view: decision });
+    }
+    for (const handoff of model.handoffs) {
+        entries.push({ kind: "handoff", key: handoff.phaseRef, id: handoff.phaseRef, ref: handoff.phaseRef, parents: { phaseRef: handoff.phaseRef }, view: handoff });
+    }
+    for (const idea of model.ideas) {
+        entries.push({ kind: "idea", key: idea.id, id: idea.id, ref: idea.ref, parents: {}, view: idea });
+    }
+    return entries;
+}

package/dist/handoff-reply.d.ts

@@ -3,9 +3,10 @@
  *
  * Every adapter (MCP, Pi, and any future harness) calls the same builders
  * here instead of assembling its own text/structuredContent pair. Each
- * builder returns exactly one copy of every piece of information: the
- * human-readable channel (`text`) and the machine-readable channel
- * (`structured`) never both carry the same field. Which channel is
+ * builder returns one canonical structured shape plus human-readable text.
+ * Most large fields still live in only one channel, but the handoff body is
+ * deliberately duplicated in `structured.content` for hosts that expose only
+ * structuredContent to the agent. Which channel is
  * canonical for a given piece of content is decided per field below, based
  * on what a structuredContent-only host needs in order to act (see the
  * per-field comments) rather than by a single blanket rule — see AGENTS.md
@@ -74,13 +75,11 @@ export type HandoffShowReplyInput = {
  * empty, archived, and active branches through one shared shape so no
  * surface keeps its own construction.
  *
- * Placement: the resume capsule body is prose meant to be read, and every
- * existing consumer reads it from `text` (never from `structured`), so
- * `text` is its one home; `structured` carries only `fullLength`/
- * `truncated` flags plus the identifiers, hash, and verification flags a
- * structuredContent-only host needs to drive the candidate-then-verify
- * contract (call verify with the right hash) without needing the prose
- * itself.
+ * Placement: the resume capsule body is prose that must be read by the
+ * agent before verify/resume. It is intentionally present in both `text` and
+ * `structured.content`; some hosts surface only structuredContent, and a
+ * phase ref plus hash is not enough to resume safely. `fullLength` and
+ * `truncated` describe the bounded body in both channels.
  */
 export declare function buildHandoffShowReply(input: HandoffShowReplyInput): HandoffReply;
 /** Single source of truth for the prepare-reply evidence-contract sentence,

package/dist/handoff-reply.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"handoff-reply.d.ts","sourceRoot":"","sources":["../src/handoff-reply.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,KAAK,EAAE,wBAAwB,EAA6B,KAAK,EAAE,MAAM,aAAa,CAAC;AAC9F,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,EAGL,KAAK,oBAAoB,EAEzB,KAAK,iBAAiB,EACvB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzD;;;;;;GAMG;AACH,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,oBAAoB,EAAE,MAAM,GAAE,SAAS,GAAG,aAAyB,GAAG,aAAa,CAMrI;AAED,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,OAAO,CAAC;CACpB;AAED;;;;;;oBAMoB;AACpB,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,MAAM,GAAG,qBAAqB,CAKjF;AA8CD;6CAC6C;AAC7C,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACrC;AAmCD,MAAM,MAAM,qBAAqB,GAC7B;IACE,IAAI,EAAE,OAAO,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,wBAAwB,GAAG,IAAI,CAAC;CAC/C,GACD;IACE,IAAI,EAAE,UAAU,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,iEAAiE;IACjE,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,wBAAwB,GAAG,IAAI,CAAC;CAC/C,GACD;IACE,IAAI,EAAE,QAAQ,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,KAAK,CAAC;IACb,YAAY,EAAE,YAAY,CAAC;CAC5B,CAAC;AAEN;;;;;;;;;;;;GAYG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,qBAAqB,GAAG,YAAY,CAsEhF;AAED;wDACwD;AACxD,eAAO,MAAM,iCAAiC,0IAC2F,CAAC;AAE1I,MAAM,WAAW,wBAAwB;IACvC,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,iBAAiB,CAAC;CAC1B;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,wBAAwB,GAAG,YAAY,CAkFtF"}
+{"version":3,"file":"handoff-reply.d.ts","sourceRoot":"","sources":["../src/handoff-reply.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,KAAK,EAAE,wBAAwB,EAA6B,KAAK,EAAE,MAAM,aAAa,CAAC;AAC9F,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,EAGL,KAAK,oBAAoB,EAEzB,KAAK,iBAAiB,EACvB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzD;;;;;;GAMG;AACH,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,oBAAoB,EAAE,MAAM,GAAE,SAAS,GAAG,aAAyB,GAAG,aAAa,CAMrI;AAED,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,OAAO,CAAC;CACpB;AAED;;;;;;oBAMoB;AACpB,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,MAAM,GAAG,qBAAqB,CAKjF;AA8CD;6CAC6C;AAC7C,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACrC;AAmCD,MAAM,MAAM,qBAAqB,GAC7B;IACE,IAAI,EAAE,OAAO,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,wBAAwB,GAAG,IAAI,CAAC;CAC/C,GACD;IACE,IAAI,EAAE,UAAU,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,iEAAiE;IACjE,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,wBAAwB,GAAG,IAAI,CAAC;CAC/C,GACD;IACE,IAAI,EAAE,QAAQ,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,KAAK,CAAC;IACb,YAAY,EAAE,YAAY,CAAC;CAC5B,CAAC;AAEN;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,qBAAqB,GAAG,YAAY,CAwEhF;AAED;wDACwD;AACxD,eAAO,MAAM,iCAAiC,0IAC2F,CAAC;AAE1I,MAAM,WAAW,wBAAwB;IACvC,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,iBAAiB,CAAC;CAC1B;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,wBAAwB,GAAG,YAAY,CAkFtF"}

package/dist/handoff-reply.js

@@ -105,13 +105,11 @@ function handoffAuditForTransport(audit) {
  * empty, archived, and active branches through one shared shape so no
  * surface keeps its own construction.
  *
- * Placement: the resume capsule body is prose meant to be read, and every
- * existing consumer reads it from `text` (never from `structured`), so
- * `text` is its one home; `structured` carries only `fullLength`/
- * `truncated` flags plus the identifiers, hash, and verification flags a
- * structuredContent-only host needs to drive the candidate-then-verify
- * contract (call verify with the right hash) without needing the prose
- * itself.
+ * Placement: the resume capsule body is prose that must be read by the
+ * agent before verify/resume. It is intentionally present in both `text` and
+ * `structured.content`; some hosts surface only structuredContent, and a
+ * phase ref plus hash is not enough to resume safely. `fullLength` and
+ * `truncated` describe the bounded body in both channels.
  */
 export function buildHandoffShowReply(input) {
     if (input.kind === "empty") {
@@ -148,6 +146,7 @@ export function buildHandoffShowReply(input) {
                 archiveFile: input.archiveFile,
                 fullLength: bounded.fullLength,
                 truncated: bounded.truncated,
+                content: bounded.content,
                 supportingDocuments,
                 empty: false,
                 resumeReady: false,
@@ -174,6 +173,7 @@ export function buildHandoffShowReply(input) {
             phaseWorkMap: workMapForTransport(phaseWorkMap, false),
             fullLength: bounded.fullLength,
             truncated: bounded.truncated,
+            content: bounded.content,
             contentHash,
             persistenceVerified,
             resumeReady,

package/dist/index.d.ts

@@ -1,4 +1,6 @@
 export * from "./naming.js";
+export * from "./api-v1.js";
+export * from "./session-focus.js";
 export * from "./refs.js";
 export * from "./render-utils.js";
 export * from "./pagination.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,mBAAmB,CAAC;AAClC,cAAc,iBAAiB,CAAC;AAChC,cAAc,qBAAqB,CAAC;AACpC,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,YAAY,CAAC;AAC3B,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,yBAAyB,CAAC;AACxC,cAAc,yBAAyB,CAAC;AACxC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,uBAAuB,CAAC;AACtC,cAAc,sBAAsB,CAAC;AACrC,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,qBAAqB,CAAC;AACpC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,8BAA8B,CAAC;AAC7C,cAAc,gCAAgC,CAAC;AAC/C,cAAc,sBAAsB,CAAC;AACrC,cAAc,iBAAiB,CAAC;AAChC,cAAc,cAAc,CAAC;AAC7B,cAAc,8BAA8B,CAAC;AAC7C,cAAc,sBAAsB,CAAC;AACrC,cAAc,0BAA0B,CAAC;AACzC,cAAc,yBAAyB,CAAC;AACxC,cAAc,qBAAqB,CAAC;AACpC,cAAc,kBAAkB,CAAC;AACjC,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,mBAAmB,EAAE,kCAAkC,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,cAAc,EAAE,uBAAuB,EAAE,eAAe,EAAE,MAAM,EAAE,KAAK,eAAe,EAAE,KAAK,eAAe,EAAE,KAAK,wBAAwB,EAAE,KAAK,qBAAqB,EAAE,KAAK,2BAA2B,EAAE,KAAK,2BAA2B,EAAE,KAAK,6BAA6B,EAAE,KAAK,8BAA8B,EAAE,KAAK,mBAAmB,EAAE,KAAK,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAC3hB,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,YAAY,EAAE,eAAe,EAAE,WAAW,EAAE,aAAa,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,oBAAoB,CAAC;AACnC,cAAc,WAAW,CAAC;AAC1B,cAAc,mBAAmB,CAAC;AAClC,cAAc,iBAAiB,CAAC;AAChC,cAAc,qBAAqB,CAAC;AACpC,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,YAAY,CAAC;AAC3B,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,yBAAyB,CAAC;AACxC,cAAc,yBAAyB,CAAC;AACxC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,uBAAuB,CAAC;AACtC,cAAc,sBAAsB,CAAC;AACrC,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,qBAAqB,CAAC;AACpC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,8BAA8B,CAAC;AAC7C,cAAc,gCAAgC,CAAC;AAC/C,cAAc,sBAAsB,CAAC;AACrC,cAAc,iBAAiB,CAAC;AAChC,cAAc,cAAc,CAAC;AAC7B,cAAc,8BAA8B,CAAC;AAC7C,cAAc,sBAAsB,CAAC;AACrC,cAAc,0BAA0B,CAAC;AACzC,cAAc,yBAAyB,CAAC;AACxC,cAAc,qBAAqB,CAAC;AACpC,cAAc,kBAAkB,CAAC;AACjC,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,mBAAmB,EAAE,kCAAkC,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,cAAc,EAAE,uBAAuB,EAAE,eAAe,EAAE,MAAM,EAAE,KAAK,eAAe,EAAE,KAAK,eAAe,EAAE,KAAK,wBAAwB,EAAE,KAAK,qBAAqB,EAAE,KAAK,2BAA2B,EAAE,KAAK,2BAA2B,EAAE,KAAK,6BAA6B,EAAE,KAAK,8BAA8B,EAAE,KAAK,mBAAmB,EAAE,KAAK,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAC3hB,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,YAAY,EAAE,eAAe,EAAE,WAAW,EAAE,aAAa,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -1,4 +1,6 @@
 export * from "./naming.js";
+export * from "./api-v1.js";
+export * from "./session-focus.js";
 export * from "./refs.js";
 export * from "./render-utils.js";
 export * from "./pagination.js";

package/dist/plan-store.d.ts

@@ -256,6 +256,7 @@ export declare class PlanStore {
     private generatedDir;
     private codebasePath;
     private resumePath;
+    private resumeSessionsPath;
     private activityPath;
     private projectContextReadsPath;
     private localRoot;
@@ -303,7 +304,8 @@ export declare class PlanStore {
     /** Read-only manifest load. Upgrading legacy `.local` state is explicit
      * maintenance (`repair`), never an incidental side effect of opening a plan. */
     loadManifest(): Promise<Manifest>;
-    loadProject(): Promise<Project>;
+    /** With a session id, `workDeviations` holds only that session's side tasks (plus unowned legacy ones); without, all of them. */
+    loadProject(sessionId?: string): Promise<Project>;
     /**
      * Reserve immutable human identifiers without touching tracked `project.json`.
      * Worktrees in the same clone share `.git/agent-plan/allocations`, guarded by
@@ -331,8 +333,17 @@ export declare class PlanStore {
     loadFeatures(): Promise<FeaturesDocument>;
     loadCodebaseProfile(): Promise<CodebaseProfile | null>;
     saveCodebaseProfile(profile: CodebaseProfile): Promise<void>;
-    loadResume(): Promise<ResumeFocus | null>;
-    saveResume(resume: ResumeFocus): Promise<void>;
+    /** The project-level resume focus (the one a sessionless caller sees). */
+    private loadProjectResume;
+    private loadResumeSessions;
+    /** Read-modify-write of the per-session entries under the planner's write lock. */
+    private updateResumeSessions;
+    /**
+     * The resume focus. With a session id, that session's own entry; a session that has
+     * none yet inherits the project-level focus for reading. Without one, the project-level focus.
+     */
+    loadResume(sessionId?: string): Promise<ResumeFocus | null>;
+    saveResume(resume: ResumeFocus, sessionId?: string): Promise<void>;
     /**
      * Authorize a temporary guard bypass so edit/write tools may proceed even
      * when no task is in-progress. Harness-agnostic: stored in resume.json so
@@ -347,7 +358,7 @@ export declare class PlanStore {
     loadActivityLog(): Promise<ActivityLog>;
     appendActivity(type: string, ref: string, summary: string): Promise<ActivityEntry>;
     /** Derive an up-to-date resume focus from the current workspace state. */
-    refreshResume(notes?: string, lastSessionSummary?: string): Promise<ResumeFocus>;
+    refreshResume(notes?: string, lastSessionSummary?: string, sessionId?: string): Promise<ResumeFocus>;
     loadRequirements(): Promise<RequirementsDocument>;
     loadIdeas(): Promise<IdeasDocument>;
     linkedRequirementsForPhase(phaseId: string): Promise<Requirement[]>;
@@ -460,8 +471,12 @@ export declare class PlanStore {
     /** Apply and verify the legacy project-context migration. Callers must invoke
      * this only from an explicit preparation or compatibility-recovery flow. */
     migrateLegacyProjectContext(): Promise<LegacyProjectContextMigrationResult>;
+    /** Every session's side tasks. Selection needs them all: recommendNextTask hides other sessions' on its own. */
+    listAllWorkDeviations(): Promise<WorkDeviation[]>;
     /** Persist an explicitly approved work deviation without coupling it to a harness. */
-    addWorkDeviation(deviation: WorkDeviation): Promise<Project>;
+    addWorkDeviation(deviation: Omit<WorkDeviation, "ownerSession"> & {
+        ownerSession?: string;
+    }, sessionId?: string): Promise<Project>;
     /** Advance a deviation while retaining its complete audit and return stack. */
     setWorkDeviationState(id: string, state: "active" | "resume-required" | "resolved" | "resumed" | "canceled", timestamp?: string): Promise<Project>;
     updateFeatures(updater: (f: FeaturesDocument) => FeaturesDocument): Promise<FeaturesDocument>;