@oisin-ee/pi-todo 0.7.2 → 0.9.0

package/src/runtime-fixture.ts

@@ -0,0 +1,209 @@
+import {
+  DefaultResourceLoader,
+  ModelRuntime,
+  SessionManager,
+  SettingsManager,
+  createAgentSession,
+  createCodemodeExtension,
+  createEventBus,
+} from "@earendil-works/pi-coding-agent";
+import {
+  InMemoryCredentialStore,
+  InMemoryModelsStore,
+  fauxAssistantMessage,
+  fauxProvider,
+  fauxToolCall,
+} from "@earendil-works/pi-ai";
+import type { ExtensionFactory } from "@earendil-works/pi-coding-agent";
+import type { TaskProviderV1 } from "./provider.ts";
+import type { TodoParams } from "./tool.ts";
+import { Type } from "typebox";
+import { contract } from "./contract-fixture.ts";
+import piTodo from "./index.ts";
+import { registerSeedSource } from "./seed-fixture.ts";
+
+type Session = Awaited<ReturnType<typeof createAgentSession>>["session"];
+interface Startup {
+  readonly cwd: string;
+  readonly seedPath: string;
+}
+interface RuntimeFixture {
+  readonly session: Readonly<Pick<Session, "dispose" | "abort" | "messages">> & {
+    readonly extensionRunner: Readonly<Pick<Session["extensionRunner"], "emitToolResult" | "emit">>;
+  };
+  readonly manager: SessionManager;
+  readonly provider: () => TaskProviderV1;
+  readonly call: (name: string, args: Readonly<Record<string, string>>) => Promise<void>;
+  readonly create: () => Promise<void>;
+  readonly todo: (params: TodoParams) => Promise<unknown>;
+}
+
+/**
+ * Creates resources without user configuration or external services.
+ * @param {ExtensionFactory} later Optional additional guard or test tool.
+ * @param {boolean} collision Whether the other todo owner loads first.
+ * @param {Startup | undefined} startup Optional worker startup configuration.
+ * @returns {object} Local resource owners.
+ */
+const resources = (
+    later: ExtensionFactory | undefined,
+    collision: boolean,
+    startup: Startup | undefined,
+  ): {
+    events: ReturnType<typeof createEventBus>;
+    manager: SessionManager;
+    settings: SettingsManager;
+    loader: DefaultResourceLoader;
+  } => {
+    const events = createEventBus(),
+      manager = SessionManager.inMemory(),
+      settings = SettingsManager.inMemory({
+        compaction: { enabled: false },
+        retry: { enabled: false },
+      }),
+      loader = new DefaultResourceLoader({
+        additionalExtensionPaths: collision ? [] : [new URL("index.ts", import.meta.url).pathname],
+        agentDir: "/nonexistent/pi-todo-test",
+        cwd: startup?.cwd ?? "/tmp",
+        eventBus: events,
+        extensionFactories: [
+          createCodemodeExtension(),
+          ...(later === undefined ? [] : [later]),
+          ...(collision ? [piTodo] : []),
+        ],
+        noContextFiles: true,
+        noExtensions: true,
+        noPromptTemplates: true,
+        noSkills: true,
+        noThemes: true,
+        settingsManager: settings,
+      });
+    if (startup !== undefined) {
+      registerSeedSource(events, { path: startup.seedPath, version: 1 });
+    }
+    return { events, loader, manager, settings };
+  },
+  /**
+   * Requires one synchronous response from the real event bus.
+   * @param {Readonly<object>} events Runtime event bus.
+   * @returns {TaskProviderV1} Acquired extension capability.
+   */
+  acquire = (events: Readonly<ReturnType<typeof createEventBus>>): TaskProviderV1 => {
+    const replies: TaskProviderV1[] = [],
+      version = 1;
+    events.emit("oisin.tasks.acquire.v1", {
+      reply: (value: TaskProviderV1): void => {
+        replies.push(value);
+      },
+      version,
+    });
+    const [provider] = replies;
+    if (provider === undefined || replies.length !== version) {
+      throw new Error("Expected exactly one synchronous provider");
+    }
+    return provider;
+  },
+  /**
+   * Executes the registered todo entry point, including its persistence checks.
+   * @param {Session} session Real SDK session.
+   * @param {TodoParams} params Requested mutation.
+   * @returns {Promise<unknown>} Actual tool result.
+   */
+  todoCall = async (
+    session: {
+      readonly extensionRunner: Readonly<
+        Pick<Session["extensionRunner"], "getToolDefinition" | "createToolContext">
+      >;
+    },
+    params: TodoParams,
+  ): Promise<unknown> => {
+    const tool = session.extensionRunner.getToolDefinition("todo");
+    if (tool === undefined) {
+      throw new Error("Missing todo registration");
+    }
+    return tool.execute(
+      "review",
+      params,
+      undefined,
+      undefined,
+      session.extensionRunner.createToolContext("review", new AbortController().signal),
+    );
+  },
+  /**
+   * Executes a scripted tool request through the actual model runtime.
+   * @param {Session} session Session execution owner.
+   * @param {Readonly<ReturnType<typeof fauxProvider>>} faux Scripted provider.
+   * @returns {RuntimeFixture["call"]} Request function.
+   */
+  caller =
+    (
+      session: Readonly<Pick<Session, "prompt">>,
+      faux: Readonly<Pick<ReturnType<typeof fauxProvider>, "setResponses">>,
+    ): RuntimeFixture["call"] =>
+    async (name, args): Promise<void> => {
+      faux.setResponses([
+        fauxAssistantMessage(fauxToolCall(name, args)),
+        fauxAssistantMessage("Done."),
+      ]);
+      await session.prompt("Exercise one tool.");
+    },
+  /**
+   * Loads the real runner and codemode with a scripted model.
+   * @param {ExtensionFactory} later Additional extension.
+   * @param {boolean} collision Loads a competing owner first.
+   * @param {Startup | undefined} startup Optional worker startup configuration.
+   * @returns {Promise<RuntimeFixture>} Isolated runtime and callers.
+   */
+  runtimeFixture = async (
+    later?: ExtensionFactory,
+    collision = false,
+    startup?: Startup,
+  ): Promise<RuntimeFixture> => {
+    const setup = resources(later, collision, startup),
+      modelRuntime = await ModelRuntime.create({
+        credentials: new InMemoryCredentialStore(),
+        modelsPath: null,
+        modelsStore: new InMemoryModelsStore(),
+        refreshOnCreate: false,
+      }),
+      faux = fauxProvider({ tokensPerSecond: 0 });
+    modelRuntime.registerNativeProvider(faux.provider);
+    await setup.loader.reload();
+    const { session } = await createAgentSession({
+      cwd: startup?.cwd ?? "/tmp",
+      model: faux.getModel(),
+      modelRuntime,
+      resourceLoader: setup.loader,
+      sessionManager: setup.manager,
+      settingsManager: setup.settings,
+      thinkingLevel: "off",
+    });
+    await session.bindExtensions({});
+    session.setActiveToolsByName([...session.getActiveToolNames(), "codemode"]);
+    return {
+      call: caller(session, faux),
+      create: async (): Promise<void> => {
+        await todoCall(session, {
+          items: [{ content: "Build", contract: contract(), key: "build" }],
+          op: "init",
+          start: "build",
+        });
+      },
+      manager: setup.manager,
+      provider: () => acquire(setup.events),
+      session,
+      todo: async (params): Promise<unknown> => todoCall(session, params),
+    };
+  },
+  /**
+   * Produces a deterministic tool result.
+   * @returns {object} Successful content.
+   */
+  emptyResult = (): { content: [{ type: "text"; text: string }]; details: undefined } => ({
+    content: [{ text: "ok", type: "text" }],
+    details: undefined,
+  }),
+  emptyParameters = Type.Object({});
+
+export { emptyParameters, emptyResult, runtimeFixture };
+export type { RuntimeFixture };

package/src/schema.ts

@@ -0,0 +1,86 @@
+import { StringEnum } from "@earendil-works/pi-ai";
+import { Type } from "typebox";
+
+const strings = Type.Immutable(Type.Array(Type.String())),
+  scope = Type.Immutable(
+    Type.Object(
+      {
+        generates: strings,
+        owns: strings,
+        reads: strings,
+        repositoryId: Type.String(),
+      },
+      { additionalProperties: false },
+    ),
+  ),
+  self = Type.Object({ kind: Type.Literal("self") }, { additionalProperties: false }),
+  worker = Type.Object(
+    { kind: Type.Literal("worker"), profile: Type.String() },
+    { additionalProperties: false },
+  ),
+  assignment = Type.Union([self, worker]),
+  command = Type.Object(
+    { argv: strings, cwd: Type.String(), expected: Type.String(), kind: Type.Literal("command") },
+    { additionalProperties: false },
+  ),
+  review = Type.Object(
+    { artifact: Type.String(), criterion: Type.String(), kind: Type.Literal("review") },
+    { additionalProperties: false },
+  ),
+  acceptance = Type.Union([command, review]),
+  fields = Type.Object(
+    {
+      acceptance: Type.Optional(acceptance),
+      assignment: Type.Optional(assignment),
+      deliverable: Type.Optional(Type.String()),
+      dependsOn: Type.Optional(strings),
+      scope: Type.Optional(scope),
+    },
+    { additionalProperties: false },
+  ),
+  contract = Type.Immutable(fields),
+  draftFields = Type.Object(
+    {
+      content: Type.String(),
+      contract: Type.Optional(contract),
+      key: Type.Optional(Type.String()),
+    },
+    { additionalProperties: false },
+  ),
+  draft = Type.Immutable(draftFields),
+  leaf = Type.Union([Type.String(), draft]),
+  subtasks = Type.Immutable(Type.Array(leaf)),
+  outcome = Type.Immutable(
+    Type.Object({ content: Type.String(), subtasks }, { additionalProperties: false }),
+  ),
+  item = Type.Union([leaf, outcome]),
+  items = Type.Immutable(Type.Array(item)),
+  evidence = Type.String({
+    description: "Concrete acceptance result or integration-review evidence. Required for done.",
+  }),
+  parent = Type.String({
+    description: "Parent ID. Exact content is accepted only for unmigrated legacy records.",
+  }),
+  start = Type.String({
+    description: "Atomically start this ID or creation key with init/append/update.",
+  }),
+  task = Type.String({
+    description:
+      "Unit ID, or exact legacy content before migration. Children can use their ID without parent.",
+  }),
+  parameters = Type.Immutable(
+    Type.Object(
+      {
+        contract: Type.Optional(contract),
+        evidence: Type.Optional(evidence),
+        items: Type.Optional(items),
+        op: StringEnum(["init", "start", "done", "drop", "append", "view", "update"] as const),
+        parent: Type.Optional(parent),
+        start: Type.Optional(start),
+        task: Type.Optional(task),
+      },
+      { additionalProperties: false },
+    ),
+  );
+
+export { parameters };

package/src/seed-fixture.ts

@@ -0,0 +1,35 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+const version = 1;
+
+interface Query {
+  readonly version: number;
+  readonly reply: (value: unknown) => void;
+}
+
+/**
+ * Checks the transport request before a fixture responds.
+ * @param {unknown} request Event payload.
+ * @returns {boolean} Whether the response callback exists.
+ */
+const query = (request: unknown): request is Query =>
+    typeof request === "object" &&
+    request !== null &&
+    "version" in request &&
+    request.version === version &&
+    "reply" in request &&
+    typeof request.reply === "function",
+  /**
+   * Supplies an executor response without loading execution machinery.
+   * @param {Readonly<ExtensionAPI["events"]>} events Synchronous runtime bus.
+   * @param {unknown} response Test response.
+   */
+  registerSeedSource = (events: Readonly<ExtensionAPI["events"]>, response: unknown): void => {
+    events.on("oisin.tasks.seed-source.v1", (request: unknown): void => {
+      if (query(request)) {
+        request.reply(response);
+      }
+    });
+  };
+
+export { registerSeedSource };

package/src/seed-transport.ts

@@ -0,0 +1,52 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+const version = 1,
+  empty = 0,
+  /**
+   * Validates one executor response without interpreting task state.
+   * @param {unknown} source Untrusted transport response.
+   * @returns {string | undefined} Source path or ordinary launch.
+   */
+  sourcePath = (source: unknown): string | undefined => {
+    if (
+      typeof source !== "object" ||
+      source === null ||
+      !("version" in source) ||
+      source.version !== version ||
+      !("path" in source) ||
+      Object.keys(source).some((key) => key !== "version" && key !== "path")
+    ) {
+      throw new Error("IMPORT_FAILED: invalid seed source");
+    }
+    if (source.path === null) {
+      return undefined;
+    }
+    if (typeof source.path !== "string" || source.path.trim().length === empty) {
+      throw new Error("IMPORT_FAILED: invalid seed path");
+    }
+    return source.path;
+  },
+  /**
+   * Reads executor-owned launch transport without registering an executor flag.
+   * @param {Readonly<ExtensionAPI["events"]>} events Synchronous extension event bus.
+   * @returns {string | undefined} Validated source path, or no managed launch.
+   */
+  seedPath = (events: Readonly<ExtensionAPI["events"]>): string | undefined => {
+    const replies: unknown[] = [];
+    events.emit("oisin.tasks.seed-source.v1", {
+      reply: (value: unknown): void => {
+        replies.push(value);
+      },
+      version,
+    });
+    if (replies.length === empty) {
+      return undefined;
+    }
+    if (replies.length !== version) {
+      throw new Error("IMPORT_FAILED: ambiguous seed source");
+    }
+    const [source] = replies;
+    return sourcePath(source);
+  };
+
+export { seedPath };

package/src/source.ts

@@ -4,7 +4,15 @@
  * path. The two differ when the path has a symlink, such as macOS `/tmp` or a
  * linked agent directory, so both are compared after resolving symlinks.
  */
-import { existsSync, realpathSync } from "node:fs";
+import {
+  closeSync,
+  constants,
+  existsSync,
+  fstatSync,
+  openSync,
+  readFileSync,
+  realpathSync,
+} from "node:fs";
 
 const OWN = realpathSync(new URL("index.ts", import.meta.url)),
   /**
@@ -13,6 +21,28 @@ const OWN = realpathSync(new URL("index.ts", import.meta.url)),
    * @param {string} path A tool's `sourceInfo.path`.
    * @returns {boolean} Whether the file is this package's `index.ts`.
    */
-  isOwnSource = (path: string): boolean => existsSync(path) && realpathSync(path) === OWN;
+  isOwnSource = (path: string): boolean => existsSync(path) && realpathSync(path) === OWN,
+  /**
+   * Reads only a bounded regular transport file owned by the executor.
+   * @param {string} path Seed artifact path.
+   * @returns {string} Untrusted JSON for Rust validation.
+   */
+  seedSource = (path: string): string => {
+    const descriptor = openSync(path, constants.O_RDONLY | constants.O_NONBLOCK),
+      maximum = 1_048_576;
+    try {
+      const metadata = fstatSync(descriptor);
+      if (!metadata.isFile() || metadata.size > maximum) {
+        throw new Error("IMPORT_FAILED: seed must be a regular file of at most 1 MiB");
+      }
+      const bytes = readFileSync(descriptor);
+      if (bytes.byteLength > maximum) {
+        throw new Error("IMPORT_FAILED: seed exceeds 1 MiB");
+      }
+      return new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+    } finally {
+      closeSync(descriptor);
+    }
+  };
 
-export { isOwnSource };
+export { isOwnSource, seedSource };

package/src/state.ts

@@ -1,4 +1,6 @@
 import type { CustomEntry, SessionEntry } from "@earendil-works/pi-coding-agent";
+import type { ExecutionRef, TodoList, UnitRef } from "./wasm.ts";
+import { parse } from "./wasm.ts";
 
 /** The snapshot of a branch with no list yet. */
 const EMPTY: unknown = { tasks: [] },
@@ -23,6 +25,81 @@ const EMPTY: unknown = { tasks: [] },
       }
     }
     return EMPTY;
+  },
+  /**
+   * Resolves the first branch entry for a contract revision.
+   * @param {Readonly<UnitRef>} reference Revision identity.
+   * @param {string} entryId Containing Pi entry.
+   * @param {Readonly<Map<string, string>>} origins Prior branch origins.
+   * @returns {string} The revision's originating entry.
+   */
+  originFor = (
+    reference: Readonly<UnitRef>,
+    entryId: string,
+    origins: Readonly<Map<string, string>>,
+  ): string => {
+    const key = JSON.stringify([reference.sessionId, reference.unitId, reference.revision]),
+      origin = origins.get(key) ?? entryId;
+    origins.set(key, origin);
+    return origin;
   };
 
-export { STATE_ENTRY, latestSnapshot };
+/** Derives entry provenance without rewriting the imported lead reference. */
+class Provenance {
+  readonly #origins = new Map<string, string>();
+  readonly #seals = new Map<string, string>();
+
+  /**
+   * Resolves contract and seal provenance for one task snapshot.
+   * @param {Readonly<object>} unit Task provenance fields.
+   * @param {string} entryId Snapshot identity.
+   */
+  public resolve(
+    unit: {
+      readonly reference: Readonly<UnitRef>;
+      readonly imported:
+        | {
+            readonly seed: { readonly execution: Readonly<ExecutionRef> };
+            readonly seal: { readonly entryId: string } | undefined;
+          }
+        | undefined;
+    },
+    entryId: string,
+  ): void {
+    if (unit.imported === undefined) {
+      Object.assign(unit.reference, {
+        contractEntryId: originFor(unit.reference, entryId, this.#origins),
+      });
+    } else if (unit.imported.seal !== undefined) {
+      const key = JSON.stringify(unit.imported.seed.execution),
+        sealEntry = this.#seals.get(key) ?? entryId;
+      this.#seals.set(key, sealEntry);
+      Object.assign(unit.imported.seal, { entryId: sealEntry });
+    }
+  }
+}
+
+/**
+ * Reads revision origins from the entries that first introduced them.
+ * Status-only snapshots cannot move a revision's origin.
+ * @param {readonly SessionEntry[]} branch Current branch in chronological order.
+ * @returns {TodoList} Validated snapshot with derived provenance.
+ */
+const branchSnapshot = (branch: readonly SessionEntry[]): TodoList => {
+  const provenance = new Provenance();
+  let current: TodoList = { tasks: [] };
+  for (const entry of branch.filter((candidate) => isStateEntry(candidate))) {
+    current = parse(entry.data);
+    for (const task of current.tasks.flatMap((root) => [root, ...(root.subtasks ?? [])])) {
+      if (task.unit !== undefined) {
+        provenance.resolve(
+          { imported: task.unit.imported, reference: task.unit.reference },
+          entry.id,
+        );
+      }
+    }
+  }
+  return current;
+};
+
+export { STATE_ENTRY, branchSnapshot, latestSnapshot };

package/src/tool.ts

@@ -1,22 +1,17 @@
-import { STATE_ENTRY, latestSnapshot } from "./state.ts";
-import { apply, parse, view } from "./wasm.ts";
+import { STATE_ENTRY, branchSnapshot } from "./state.ts";
+import { apply, view } from "./wasm.ts";
 import type { SessionEntry } from "@earendil-works/pi-coding-agent";
+import type { Static } from "typebox";
 import type { TodoList } from "./wasm.ts";
+import type { parameters } from "./schema.ts";
 import { workUnitGuidance } from "./guidance.ts";
 
 /** One `todo` call, as the schema in `index.ts` admits it. */
-interface TodoParams {
-  readonly op: "init" | "start" | "done" | "drop" | "append" | "view";
-  readonly items?: readonly (
-    | string
-    | { readonly content: string; readonly subtasks: readonly string[] }
-  )[];
-  readonly parent?: string;
-  readonly task?: string;
-}
+type TodoParams = Static<typeof parameters>;
 
 /** What a call reads from and writes to the session. */
 interface TodoSession {
+  readonly sessionId: string;
   readonly branch: () => readonly SessionEntry[];
   readonly append: (customType: string, list: TodoList) => void;
 }
@@ -47,12 +42,18 @@ const result = (list: TodoList, creation: boolean): TodoResult => ({
    * @returns {TodoResult} The result for the model and the renderer.
    */
   runTodo = (params: TodoParams, session: TodoSession): TodoResult => {
-    const current = parse(latestSnapshot(session.branch())),
-      { list, persist } = apply(current, params);
+    const current = branchSnapshot(session.branch()),
+      { list, persist } = apply(current, params, {
+        mutationId: crypto.randomUUID(),
+        sessionId: session.sessionId,
+      });
     if (persist) {
       session.append(STATE_ENTRY, list);
     }
-    return result(list, params.op === "init" || params.op === "append");
+    return result(
+      persist ? branchSnapshot(session.branch()) : list,
+      params.op === "init" || params.op === "append",
+    );
   };
 
 export { runTodo };

package/src/wasm.ts

@@ -14,7 +14,14 @@ initSync({
 });
 
 export {
+  active,
   apply,
+  claim,
+  inspect,
+  import_unit as importUnit,
+  imported,
+  protect,
+  settle,
   completion_reminder as completionReminder,
   init,
   parse,
@@ -22,6 +29,25 @@ export {
   widget,
 } from "./generated/todo_core.js";
 export type {
+  Acceptance,
+  ActiveUnit,
+  Assignment,
+  ClaimInput,
+  ClaimResult,
+  ImportReceipt,
+  Seed,
+  EvidenceRef,
+  ExecutionRef,
+  Settlement,
+  SettlementResult,
+  TaskBinding,
+  TaskExport,
+  ContractDraft,
+  Scope,
+  MutationContext,
+  Unit,
+  UnitContract,
+  UnitRef,
   Operation,
   ReminderFact,
   Request,