@ai-agent-forge/plugin-todo-set 0.85.0

package/README.md

@@ -0,0 +1,22 @@
+# @agent-forge/plugin-todo-set
+
+Todo-set capability plugin for [Agent Forge](https://github.com/agent-forge/agent-forge), extracted from the host's
+`src/capabilities/todo-set.ts` (D-075 S4, first B-class batch). It registers a single tool, `todo_update`: a
+self-contained todo state machine whose `planId` field softly references a plan by plain id.
+
+Todos persist as append-only `todo.state` session entries and every change is announced as a `todo.changed` event. The
+soft reference is advisory (#10): an unknown `planId` never fails the write — the tool response carries a `warning`
+field instead, read from the session branch's latest `plan.state` snapshot through the shared session entry protocol.
+
+## Install
+
+```sh
+# from a local checkout
+agent-forge plugin install ./plugins/todo-set
+
+# from npm
+agent-forge plugin install @ai-agent-forge/plugin-todo-set
+```
+
+Suites declare the capability through the `builtin.todo-set` short id; after the S4 split that id is assembled from
+this package through the install store (bootstrap factory manifest or manual install).

package/agent-forge.json

@@ -0,0 +1,11 @@
+{
+	"packageFormatVersion": 1,
+	"id": "agent-forge.plugin.todo-set",
+	"pluginVersion": "0.84.4",
+	"apiVersion": "1",
+	"minHostVersion": "0.84.4",
+	"platform": {
+		"os": ["windows", "macos", "linux"],
+		"runtime": [{ "name": "node" }]
+	}
+}

package/dist/entry.d.ts

@@ -0,0 +1,14 @@
+import type { CapabilityAPI } from "@agent-forge/plugin-sdk";
+/**
+ * Default-export factory consumed by the host's `loadCapabilityPluginFromManifest`.
+ *
+ * The capability factory returns its registrations as an array, while the
+ * manifest loader contract expects `void` or a single `{ dispose() }` instance
+ * (`normalizePluginInstance` does not accept arrays). The wrapper collects the
+ * registrations and disposes them in reverse order on plugin teardown — the
+ * same disposal semantics as the host's embedded `syncRegistrationFactory`.
+ */
+export default function createTodoSetPluginEntry(api: CapabilityAPI): Promise<{
+    dispose: () => void;
+}>;
+//# sourceMappingURL=entry.d.ts.map

package/dist/entry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entry.d.ts","sourceRoot":"","sources":["../src/entry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAG7D;;;;;;;;GAQG;AACH,wBAA8B,wBAAwB,CACrD,GAAG,EAAE,aAAa,GAChB,OAAO,CAAC;IAAE,OAAO,EAAE,MAAM,IAAI,CAAA;CAAE,CAAC,CAWlC","sourcesContent":["import type { CapabilityAPI } from \"@agent-forge/plugin-sdk\";\nimport { createCapability } from \"./index.ts\";\n\n/**\n * Default-export factory consumed by the host's `loadCapabilityPluginFromManifest`.\n *\n * The capability factory returns its registrations as an array, while the\n * manifest loader contract expects `void` or a single `{ dispose() }` instance\n * (`normalizePluginInstance` does not accept arrays). The wrapper collects the\n * registrations and disposes them in reverse order on plugin teardown — the\n * same disposal semantics as the host's embedded `syncRegistrationFactory`.\n */\nexport default async function createTodoSetPluginEntry(\n\tapi: CapabilityAPI,\n): Promise<{ dispose: () => void }> {\n\tconst registrations = await createCapability(api);\n\treturn {\n\t\tdispose: () => {\n\t\t\tfor (const registration of [...registrations].reverse()) {\n\t\t\t\t// Registration disposal in the capability runtime is synchronous;\n\t\t\t\t// void consumes the declared Promise possibility of the contract.\n\t\t\t\tvoid registration.dispose();\n\t\t\t}\n\t\t},\n\t};\n}\n"]}

package/dist/entry.js

@@ -0,0 +1,23 @@
+import { createCapability } from "./index.js";
+/**
+ * Default-export factory consumed by the host's `loadCapabilityPluginFromManifest`.
+ *
+ * The capability factory returns its registrations as an array, while the
+ * manifest loader contract expects `void` or a single `{ dispose() }` instance
+ * (`normalizePluginInstance` does not accept arrays). The wrapper collects the
+ * registrations and disposes them in reverse order on plugin teardown — the
+ * same disposal semantics as the host's embedded `syncRegistrationFactory`.
+ */
+export default async function createTodoSetPluginEntry(api) {
+    const registrations = await createCapability(api);
+    return {
+        dispose: () => {
+            for (const registration of [...registrations].reverse()) {
+                // Registration disposal in the capability runtime is synchronous;
+                // void consumes the declared Promise possibility of the contract.
+                void registration.dispose();
+            }
+        },
+    };
+}
+//# sourceMappingURL=entry.js.map

package/dist/entry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"entry.js","sourceRoot":"","sources":["../src/entry.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAE9C;;;;;;;;GAQG;AACH,MAAM,CAAC,OAAO,CAAC,KAAK,UAAU,wBAAwB,CACrD,GAAkB,EACiB;IACnC,MAAM,aAAa,GAAG,MAAM,gBAAgB,CAAC,GAAG,CAAC,CAAC;IAClD,OAAO;QACN,OAAO,EAAE,GAAG,EAAE,CAAC;YACd,KAAK,MAAM,YAAY,IAAI,CAAC,GAAG,aAAa,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC;gBACzD,kEAAkE;gBAClE,kEAAkE;gBAClE,KAAK,YAAY,CAAC,OAAO,EAAE,CAAC;YAC7B,CAAC;QAAA,CACD;KACD,CAAC;AAAA,CACF","sourcesContent":["import type { CapabilityAPI } from \"@agent-forge/plugin-sdk\";\nimport { createCapability } from \"./index.ts\";\n\n/**\n * Default-export factory consumed by the host's `loadCapabilityPluginFromManifest`.\n *\n * The capability factory returns its registrations as an array, while the\n * manifest loader contract expects `void` or a single `{ dispose() }` instance\n * (`normalizePluginInstance` does not accept arrays). The wrapper collects the\n * registrations and disposes them in reverse order on plugin teardown — the\n * same disposal semantics as the host's embedded `syncRegistrationFactory`.\n */\nexport default async function createTodoSetPluginEntry(\n\tapi: CapabilityAPI,\n): Promise<{ dispose: () => void }> {\n\tconst registrations = await createCapability(api);\n\treturn {\n\t\tdispose: () => {\n\t\t\tfor (const registration of [...registrations].reverse()) {\n\t\t\t\t// Registration disposal in the capability runtime is synchronous;\n\t\t\t\t// void consumes the declared Promise possibility of the contract.\n\t\t\t\tvoid registration.dispose();\n\t\t\t}\n\t\t},\n\t};\n}\n"]}

package/dist/index.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Todo-set capability plugin: a self-contained todo state machine, extracted
+ * from the host's `src/capabilities/todo-set.ts` (D-075 S4, first B-class
+ * batch).
+ *
+ * Todos persist as append-only `todo.state` session entries and every change
+ * is announced as a `todo.changed` event. `planId` is a soft reference: a
+ * plain string whose target is checked ADVISORILY against the plan plugin's
+ * LATEST `plan.state` snapshot (the same latest-snapshot semantics as this
+ * plugin's own {@link loadState}); an unknown id yields a response warning,
+ * never a failure (the same #10 pattern as the plan plugin's goalId check).
+ * The plugin only consumes the public `session`, `events`, and `tools`
+ * capabilities and never writes state owned by another plugin.
+ */
+import type { CapabilityAPI, DisposableRegistration } from "@agent-forge/plugin-sdk";
+export interface TodoRecord {
+    id: string;
+    /** Soft reference: a plain string; unknown ids yield a response warning, not a failure. */
+    planId: string;
+    title: string;
+    status: "pending" | "done" | "blocked";
+    revision: number;
+    evidence: string[];
+}
+export interface TodoState {
+    todos: TodoRecord[];
+}
+export declare function createCapability(api: CapabilityAPI): Promise<readonly DisposableRegistration[]> | readonly DisposableRegistration[];
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAE,sBAAsB,EAAE,MAAM,yBAAyB,CAAC;AAErF,MAAM,WAAW,UAAU;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,2FAA2F;IAC3F,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,SAAS,GAAG,MAAM,GAAG,SAAS,CAAC;IACvC,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,MAAM,WAAW,SAAS;IACzB,KAAK,EAAE,UAAU,EAAE,CAAC;CACpB;AAoFD,wBAAgB,gBAAgB,CAC/B,GAAG,EAAE,aAAa,GAChB,OAAO,CAAC,SAAS,sBAAsB,EAAE,CAAC,GAAG,SAAS,sBAAsB,EAAE,CA4ChF","sourcesContent":["/**\n * Todo-set capability plugin: a self-contained todo state machine, extracted\n * from the host's `src/capabilities/todo-set.ts` (D-075 S4, first B-class\n * batch).\n *\n * Todos persist as append-only `todo.state` session entries and every change\n * is announced as a `todo.changed` event. `planId` is a soft reference: a\n * plain string whose target is checked ADVISORILY against the plan plugin's\n * LATEST `plan.state` snapshot (the same latest-snapshot semantics as this\n * plugin's own {@link loadState}); an unknown id yields a response warning,\n * never a failure (the same #10 pattern as the plan plugin's goalId check).\n * The plugin only consumes the public `session`, `events`, and `tools`\n * capabilities and never writes state owned by another plugin.\n */\n\nimport { Type } from \"typebox\";\nimport type { CapabilityAPI, DisposableRegistration } from \"@agent-forge/plugin-sdk\";\n\nexport interface TodoRecord {\n\tid: string;\n\t/** Soft reference: a plain string; unknown ids yield a response warning, not a failure. */\n\tplanId: string;\n\ttitle: string;\n\tstatus: \"pending\" | \"done\" | \"blocked\";\n\trevision: number;\n\tevidence: string[];\n}\n\nexport interface TodoState {\n\ttodos: TodoRecord[];\n}\n\nconst stateEntry = \"todo.state\";\n/** Session protocol key of the plan plugin's snapshot entry (plugins/plan). */\nconst planStateEntry = \"plan.state\";\n\nconst todoSchema = Type.Object({\n\tid: Type.String({ description: \"Stable id of the todo to create or update\" }),\n\tplanId: Type.String({\n\t\tdescription:\n\t\t\t\"Soft reference to a plan id; an id unknown to this session's plan state yields a response warning, not a failure\",\n\t}),\n\ttitle: Type.String({ description: \"Human-readable todo title\" }),\n\trevision: Type.Integer({\n\t\tdescription: \"New revision counter; must be greater than the stored revision of an existing todo\",\n\t\tminimum: 0,\n\t}),\n\tstatus: Type.Optional(\n\t\tType.Union([Type.Literal(\"pending\"), Type.Literal(\"done\"), Type.Literal(\"blocked\")], {\n\t\t\tdescription: \"Next status; defaults to the stored status for existing todos, otherwise pending\",\n\t\t}),\n\t),\n\tevidence: Type.Optional(\n\t\tType.Array(Type.String(), {\n\t\t\tdescription: \"Evidence references; at least one is required when status is done\",\n\t\t}),\n\t),\n});\n\nfunction objectInput(first: unknown, second: unknown): Record<string, unknown> {\n\tconst value = second === undefined ? first : second;\n\tif (!value || typeof value !== \"object\" || Array.isArray(value)) throw new Error(\"Todo input must be an object\");\n\treturn value as Record<string, unknown>;\n}\n\nfunction text(value: unknown, name: string): string {\n\tif (typeof value !== \"string\" || value.trim() === \"\") throw new Error(`${name} must be a non-empty string`);\n\treturn value;\n}\n\nfunction revision(value: unknown): number {\n\tif (!Number.isInteger(value) || (value as number) < 0) throw new Error(\"revision must be a non-negative integer\");\n\treturn value as number;\n}\n\nfunction evidence(value: unknown): string[] {\n\tif (value === undefined) return [];\n\tif (!Array.isArray(value) || value.some((item) => typeof item !== \"string\" || item.trim() === \"\")) {\n\t\tthrow new Error(\"evidence must be a string array\");\n\t}\n\treturn [...(value as string[])];\n}\n\nfunction loadState(api: CapabilityAPI): TodoState {\n\tconst entries = api.session?.getBranchEntries() ?? [];\n\tconst entry = [...entries].reverse().find((item) => item.customType === stateEntry);\n\tif (!entry?.data || typeof entry.data !== \"object\") return { todos: [] };\n\tconst data = entry.data as Partial<TodoState>;\n\treturn { todos: Array.isArray(data.todos) ? [...data.todos] : [] };\n}\n\n/**\n * Whether the session branch's LATEST `plan.state` snapshot knows a plan with\n * the given id (the same latest-snapshot semantics as {@link loadState} and\n * the same advisory pattern as the plan plugin's goalKnownToSession). The\n * check is advisory only (#10): a missing plan downgrades to a warning in the\n * tool response — the soft-reference write path never fails on it.\n */\nfunction planKnownToSession(api: CapabilityAPI, planId: string): boolean {\n\tconst entries = api.session?.getBranchEntries() ?? [];\n\tfor (let index = entries.length - 1; index >= 0; index -= 1) {\n\t\tconst entry = entries[index];\n\t\tif (entry.customType !== planStateEntry) continue;\n\t\tconst data = entry.data;\n\t\tif (!data || typeof data !== \"object\" || Array.isArray(data)) return false;\n\t\tconst plans = (data as { plans?: unknown }).plans;\n\t\tif (!Array.isArray(plans)) return false;\n\t\treturn plans.some(\n\t\t\t(plan) => plan !== null && typeof plan === \"object\" && (plan as { id?: unknown }).id === planId,\n\t\t);\n\t}\n\treturn false;\n}\n\nexport function createCapability(\n\tapi: CapabilityAPI,\n): Promise<readonly DisposableRegistration[]> | readonly DisposableRegistration[] {\n\tlet state = loadState(api);\n\n\tconst persist = async (): Promise<TodoState> => {\n\t\tapi.session?.appendEntry(stateEntry, state);\n\t\tawait api.publish({ type: \"todo.changed\", version: 1, correlationId: stateEntry, data: state });\n\t\treturn state;\n\t};\n\n\tconst tool = api.registerTool({\n\t\tname: \"todo_update\",\n\t\tlabel: \"Update todo\",\n\t\tdescription: \"Update a todo that softly references a plan by id\",\n\t\tparameters: todoSchema,\n\t\texecute: async (first: unknown, second?: unknown) => {\n\t\t\tconst input = objectInput(first, second);\n\t\t\tconst id = text(input.id, \"id\");\n\t\t\tconst planId = text(input.planId, \"planId\");\n\t\t\tconst title = text(input.title, \"title\");\n\t\t\tconst nextRevision = revision(input.revision);\n\t\t\tconst current = state.todos.find((item) => item.id === id);\n\t\t\tif (current && nextRevision <= current.revision) throw new Error(`stale todo revision: ${id}`);\n\t\t\tif (current?.status === \"done\") throw new Error(`todo is terminal and cannot be updated: ${id}`);\n\t\t\tconst status =\n\t\t\t\tinput.status === undefined\n\t\t\t\t\t? (current?.status ?? \"pending\")\n\t\t\t\t\t: (text(input.status, \"status\") as TodoRecord[\"status\"]);\n\t\t\tif (![\"pending\", \"done\", \"blocked\"].includes(status)) throw new Error(\"invalid todo status\");\n\t\t\tconst values = evidence(input.evidence);\n\t\t\tif (status === \"done\" && values.length === 0) {\n\t\t\t\tthrow new Error(\"todo completion requires at least one evidence reference\");\n\t\t\t}\n\t\t\tconst record: TodoRecord = { id, planId, title, status, revision: nextRevision, evidence: values };\n\t\t\tstate = { ...state, todos: [...state.todos.filter((item) => item.id !== id), record] };\n\t\t\tconst saved = await persist();\n\t\t\tif (planKnownToSession(api, planId)) return saved;\n\t\t\treturn {\n\t\t\t\t...saved,\n\t\t\t\twarning: `planId \"${planId}\" does not match any plan in this session's plan state; the todo keeps the soft reference, but the plan is unknown`,\n\t\t\t};\n\t\t},\n\t});\n\n\treturn [tool];\n}\n"]}

package/dist/index.js

@@ -0,0 +1,136 @@
+/**
+ * Todo-set capability plugin: a self-contained todo state machine, extracted
+ * from the host's `src/capabilities/todo-set.ts` (D-075 S4, first B-class
+ * batch).
+ *
+ * Todos persist as append-only `todo.state` session entries and every change
+ * is announced as a `todo.changed` event. `planId` is a soft reference: a
+ * plain string whose target is checked ADVISORILY against the plan plugin's
+ * LATEST `plan.state` snapshot (the same latest-snapshot semantics as this
+ * plugin's own {@link loadState}); an unknown id yields a response warning,
+ * never a failure (the same #10 pattern as the plan plugin's goalId check).
+ * The plugin only consumes the public `session`, `events`, and `tools`
+ * capabilities and never writes state owned by another plugin.
+ */
+import { Type } from "typebox";
+const stateEntry = "todo.state";
+/** Session protocol key of the plan plugin's snapshot entry (plugins/plan). */
+const planStateEntry = "plan.state";
+const todoSchema = Type.Object({
+    id: Type.String({ description: "Stable id of the todo to create or update" }),
+    planId: Type.String({
+        description: "Soft reference to a plan id; an id unknown to this session's plan state yields a response warning, not a failure",
+    }),
+    title: Type.String({ description: "Human-readable todo title" }),
+    revision: Type.Integer({
+        description: "New revision counter; must be greater than the stored revision of an existing todo",
+        minimum: 0,
+    }),
+    status: Type.Optional(Type.Union([Type.Literal("pending"), Type.Literal("done"), Type.Literal("blocked")], {
+        description: "Next status; defaults to the stored status for existing todos, otherwise pending",
+    })),
+    evidence: Type.Optional(Type.Array(Type.String(), {
+        description: "Evidence references; at least one is required when status is done",
+    })),
+});
+function objectInput(first, second) {
+    const value = second === undefined ? first : second;
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error("Todo input must be an object");
+    return value;
+}
+function text(value, name) {
+    if (typeof value !== "string" || value.trim() === "")
+        throw new Error(`${name} must be a non-empty string`);
+    return value;
+}
+function revision(value) {
+    if (!Number.isInteger(value) || value < 0)
+        throw new Error("revision must be a non-negative integer");
+    return value;
+}
+function evidence(value) {
+    if (value === undefined)
+        return [];
+    if (!Array.isArray(value) || value.some((item) => typeof item !== "string" || item.trim() === "")) {
+        throw new Error("evidence must be a string array");
+    }
+    return [...value];
+}
+function loadState(api) {
+    const entries = api.session?.getBranchEntries() ?? [];
+    const entry = [...entries].reverse().find((item) => item.customType === stateEntry);
+    if (!entry?.data || typeof entry.data !== "object")
+        return { todos: [] };
+    const data = entry.data;
+    return { todos: Array.isArray(data.todos) ? [...data.todos] : [] };
+}
+/**
+ * Whether the session branch's LATEST `plan.state` snapshot knows a plan with
+ * the given id (the same latest-snapshot semantics as {@link loadState} and
+ * the same advisory pattern as the plan plugin's goalKnownToSession). The
+ * check is advisory only (#10): a missing plan downgrades to a warning in the
+ * tool response — the soft-reference write path never fails on it.
+ */
+function planKnownToSession(api, planId) {
+    const entries = api.session?.getBranchEntries() ?? [];
+    for (let index = entries.length - 1; index >= 0; index -= 1) {
+        const entry = entries[index];
+        if (entry.customType !== planStateEntry)
+            continue;
+        const data = entry.data;
+        if (!data || typeof data !== "object" || Array.isArray(data))
+            return false;
+        const plans = data.plans;
+        if (!Array.isArray(plans))
+            return false;
+        return plans.some((plan) => plan !== null && typeof plan === "object" && plan.id === planId);
+    }
+    return false;
+}
+export function createCapability(api) {
+    let state = loadState(api);
+    const persist = async () => {
+        api.session?.appendEntry(stateEntry, state);
+        await api.publish({ type: "todo.changed", version: 1, correlationId: stateEntry, data: state });
+        return state;
+    };
+    const tool = api.registerTool({
+        name: "todo_update",
+        label: "Update todo",
+        description: "Update a todo that softly references a plan by id",
+        parameters: todoSchema,
+        execute: async (first, second) => {
+            const input = objectInput(first, second);
+            const id = text(input.id, "id");
+            const planId = text(input.planId, "planId");
+            const title = text(input.title, "title");
+            const nextRevision = revision(input.revision);
+            const current = state.todos.find((item) => item.id === id);
+            if (current && nextRevision <= current.revision)
+                throw new Error(`stale todo revision: ${id}`);
+            if (current?.status === "done")
+                throw new Error(`todo is terminal and cannot be updated: ${id}`);
+            const status = input.status === undefined
+                ? (current?.status ?? "pending")
+                : text(input.status, "status");
+            if (!["pending", "done", "blocked"].includes(status))
+                throw new Error("invalid todo status");
+            const values = evidence(input.evidence);
+            if (status === "done" && values.length === 0) {
+                throw new Error("todo completion requires at least one evidence reference");
+            }
+            const record = { id, planId, title, status, revision: nextRevision, evidence: values };
+            state = { ...state, todos: [...state.todos.filter((item) => item.id !== id), record] };
+            const saved = await persist();
+            if (planKnownToSession(api, planId))
+                return saved;
+            return {
+                ...saved,
+                warning: `planId "${planId}" does not match any plan in this session's plan state; the todo keeps the soft reference, but the plan is unknown`,
+            };
+        },
+    });
+    return [tool];
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Todo-set capability plugin: a self-contained todo state machine, extracted\n * from the host's `src/capabilities/todo-set.ts` (D-075 S4, first B-class\n * batch).\n *\n * Todos persist as append-only `todo.state` session entries and every change\n * is announced as a `todo.changed` event. `planId` is a soft reference: a\n * plain string whose target is checked ADVISORILY against the plan plugin's\n * LATEST `plan.state` snapshot (the same latest-snapshot semantics as this\n * plugin's own {@link loadState}); an unknown id yields a response warning,\n * never a failure (the same #10 pattern as the plan plugin's goalId check).\n * The plugin only consumes the public `session`, `events`, and `tools`\n * capabilities and never writes state owned by another plugin.\n */\n\nimport { Type } from \"typebox\";\nimport type { CapabilityAPI, DisposableRegistration } from \"@agent-forge/plugin-sdk\";\n\nexport interface TodoRecord {\n\tid: string;\n\t/** Soft reference: a plain string; unknown ids yield a response warning, not a failure. */\n\tplanId: string;\n\ttitle: string;\n\tstatus: \"pending\" | \"done\" | \"blocked\";\n\trevision: number;\n\tevidence: string[];\n}\n\nexport interface TodoState {\n\ttodos: TodoRecord[];\n}\n\nconst stateEntry = \"todo.state\";\n/** Session protocol key of the plan plugin's snapshot entry (plugins/plan). */\nconst planStateEntry = \"plan.state\";\n\nconst todoSchema = Type.Object({\n\tid: Type.String({ description: \"Stable id of the todo to create or update\" }),\n\tplanId: Type.String({\n\t\tdescription:\n\t\t\t\"Soft reference to a plan id; an id unknown to this session's plan state yields a response warning, not a failure\",\n\t}),\n\ttitle: Type.String({ description: \"Human-readable todo title\" }),\n\trevision: Type.Integer({\n\t\tdescription: \"New revision counter; must be greater than the stored revision of an existing todo\",\n\t\tminimum: 0,\n\t}),\n\tstatus: Type.Optional(\n\t\tType.Union([Type.Literal(\"pending\"), Type.Literal(\"done\"), Type.Literal(\"blocked\")], {\n\t\t\tdescription: \"Next status; defaults to the stored status for existing todos, otherwise pending\",\n\t\t}),\n\t),\n\tevidence: Type.Optional(\n\t\tType.Array(Type.String(), {\n\t\t\tdescription: \"Evidence references; at least one is required when status is done\",\n\t\t}),\n\t),\n});\n\nfunction objectInput(first: unknown, second: unknown): Record<string, unknown> {\n\tconst value = second === undefined ? first : second;\n\tif (!value || typeof value !== \"object\" || Array.isArray(value)) throw new Error(\"Todo input must be an object\");\n\treturn value as Record<string, unknown>;\n}\n\nfunction text(value: unknown, name: string): string {\n\tif (typeof value !== \"string\" || value.trim() === \"\") throw new Error(`${name} must be a non-empty string`);\n\treturn value;\n}\n\nfunction revision(value: unknown): number {\n\tif (!Number.isInteger(value) || (value as number) < 0) throw new Error(\"revision must be a non-negative integer\");\n\treturn value as number;\n}\n\nfunction evidence(value: unknown): string[] {\n\tif (value === undefined) return [];\n\tif (!Array.isArray(value) || value.some((item) => typeof item !== \"string\" || item.trim() === \"\")) {\n\t\tthrow new Error(\"evidence must be a string array\");\n\t}\n\treturn [...(value as string[])];\n}\n\nfunction loadState(api: CapabilityAPI): TodoState {\n\tconst entries = api.session?.getBranchEntries() ?? [];\n\tconst entry = [...entries].reverse().find((item) => item.customType === stateEntry);\n\tif (!entry?.data || typeof entry.data !== \"object\") return { todos: [] };\n\tconst data = entry.data as Partial<TodoState>;\n\treturn { todos: Array.isArray(data.todos) ? [...data.todos] : [] };\n}\n\n/**\n * Whether the session branch's LATEST `plan.state` snapshot knows a plan with\n * the given id (the same latest-snapshot semantics as {@link loadState} and\n * the same advisory pattern as the plan plugin's goalKnownToSession). The\n * check is advisory only (#10): a missing plan downgrades to a warning in the\n * tool response — the soft-reference write path never fails on it.\n */\nfunction planKnownToSession(api: CapabilityAPI, planId: string): boolean {\n\tconst entries = api.session?.getBranchEntries() ?? [];\n\tfor (let index = entries.length - 1; index >= 0; index -= 1) {\n\t\tconst entry = entries[index];\n\t\tif (entry.customType !== planStateEntry) continue;\n\t\tconst data = entry.data;\n\t\tif (!data || typeof data !== \"object\" || Array.isArray(data)) return false;\n\t\tconst plans = (data as { plans?: unknown }).plans;\n\t\tif (!Array.isArray(plans)) return false;\n\t\treturn plans.some(\n\t\t\t(plan) => plan !== null && typeof plan === \"object\" && (plan as { id?: unknown }).id === planId,\n\t\t);\n\t}\n\treturn false;\n}\n\nexport function createCapability(\n\tapi: CapabilityAPI,\n): Promise<readonly DisposableRegistration[]> | readonly DisposableRegistration[] {\n\tlet state = loadState(api);\n\n\tconst persist = async (): Promise<TodoState> => {\n\t\tapi.session?.appendEntry(stateEntry, state);\n\t\tawait api.publish({ type: \"todo.changed\", version: 1, correlationId: stateEntry, data: state });\n\t\treturn state;\n\t};\n\n\tconst tool = api.registerTool({\n\t\tname: \"todo_update\",\n\t\tlabel: \"Update todo\",\n\t\tdescription: \"Update a todo that softly references a plan by id\",\n\t\tparameters: todoSchema,\n\t\texecute: async (first: unknown, second?: unknown) => {\n\t\t\tconst input = objectInput(first, second);\n\t\t\tconst id = text(input.id, \"id\");\n\t\t\tconst planId = text(input.planId, \"planId\");\n\t\t\tconst title = text(input.title, \"title\");\n\t\t\tconst nextRevision = revision(input.revision);\n\t\t\tconst current = state.todos.find((item) => item.id === id);\n\t\t\tif (current && nextRevision <= current.revision) throw new Error(`stale todo revision: ${id}`);\n\t\t\tif (current?.status === \"done\") throw new Error(`todo is terminal and cannot be updated: ${id}`);\n\t\t\tconst status =\n\t\t\t\tinput.status === undefined\n\t\t\t\t\t? (current?.status ?? \"pending\")\n\t\t\t\t\t: (text(input.status, \"status\") as TodoRecord[\"status\"]);\n\t\t\tif (![\"pending\", \"done\", \"blocked\"].includes(status)) throw new Error(\"invalid todo status\");\n\t\t\tconst values = evidence(input.evidence);\n\t\t\tif (status === \"done\" && values.length === 0) {\n\t\t\t\tthrow new Error(\"todo completion requires at least one evidence reference\");\n\t\t\t}\n\t\t\tconst record: TodoRecord = { id, planId, title, status, revision: nextRevision, evidence: values };\n\t\t\tstate = { ...state, todos: [...state.todos.filter((item) => item.id !== id), record] };\n\t\t\tconst saved = await persist();\n\t\t\tif (planKnownToSession(api, planId)) return saved;\n\t\t\treturn {\n\t\t\t\t...saved,\n\t\t\t\twarning: `planId \"${planId}\" does not match any plan in this session's plan state; the todo keeps the soft reference, but the plan is unknown`,\n\t\t\t};\n\t\t},\n\t});\n\n\treturn [tool];\n}\n"]}

package/package.json

@@ -0,0 +1,54 @@
+{
+	"name": "@ai-agent-forge/plugin-todo-set",
+	"version": "0.85.0",
+	"description": "Todo-set capability plugin for Agent Forge (todo_update state machine over session entries)",
+	"type": "module",
+	"main": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js"
+		}
+	},
+	"files": [
+		"dist",
+		"agent-forge.json",
+		"plugin.json",
+		"README.md"
+	],
+	"scripts": {
+		"clean": "shx rm -rf dist",
+		"build": "tsgo -p tsconfig.build.json",
+		"test": "vitest --run",
+		"prepublishOnly": "npm run clean && npm run build"
+	},
+	"keywords": [
+		"agent-forge",
+		"plugin",
+		"todo"
+	],
+	"author": "Agent Forge contributors",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/agent-forge/agent-forge.git",
+		"directory": "plugins/todo-set"
+	},
+	"bugs": {
+		"url": "https://github.com/agent-forge/agent-forge/issues"
+	},
+	"homepage": "https://github.com/agent-forge/agent-forge#readme",
+	"engines": {
+		"node": ">=22.19.0"
+	},
+	"dependencies": {
+		"@agent-forge/plugin-sdk": "^0.85.0",
+		"typebox": "1.3.27"
+	},
+	"devDependencies": {
+		"@agent-forge/agent-forge": "^0.85.0",
+		"shx": "0.4.0",
+		"vitest": "4.1.9"
+	}
+}

package/plugin.json

@@ -0,0 +1,8 @@
+{
+	"id": "agent-forge.plugin.todo-set",
+	"version": "0.84.4",
+	"apiVersion": "1-draft",
+	"entry": "./dist/entry.js",
+	"hostVersion": ">=0.84.4",
+	"requiredCapabilities": ["session", "events", "tools"]
+}