@davidorex/pi-context 0.29.0 → 0.30.0

package/dist/ops-registry.d.ts

@@ -1,5 +1,7 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { type TSchema } from "typebox";
+import type { DispatchContext } from "./dispatch-context.js";
+import { type ReadStructured } from "./read-element.js";
 /**
  * One substrate operation. `run(cwd, params)` returns the text payload that
  * registerAll places at `content[0].text`; everything else (param coercion,
@@ -12,13 +14,51 @@ import { type TSchema } from "typebox";
  * for that consumer and is not the enforcement point (the pi-agent-dispatch
  * auth-gate remains canonical).
  */
+/**
+ * The discriminated result of an op's `run` (TASK-012 / FGAP-013). An op returns
+ * one of three shapes, each carrying its OWN text-rendering rule so the CLI
+ * `--json` envelope can emit a real JSON value (no double-encode) while the
+ * default text surface + the in-pi Pi-tool surface stay byte-identical:
+ *   - `string`        — a prose op's human message; rendered as itself.
+ *   - `{ json: … }`   — a data op that previously returned `JSON.stringify(x, null, 2)`;
+ *                       rendered via JSON.stringify, structured value is `json`.
+ *   - `{ read: … }`   — a read op that previously returned `serializeForRead(x).content`;
+ *                       rendered via renderReadText, structured value is the
+ *                       {@link ReadStructured} (data + paging/cap metadata).
+ * {@link renderOpResultText} collapses all three back to the text both boundaries
+ * emit; the CLI `--json` branch unwraps the structured value instead.
+ */
+export type OpResult = string | {
+    json: unknown;
+} | {
+    read: ReadStructured;
+};
+/**
+ * Collapse an {@link OpResult} to the text the default CLI surface + the in-pi
+ * Pi-tool surface emit, NOW BOUNDED at the 50KB read cap (TASK-013 / FGAP-015).
+ * `{read}` → renderReadText (already capped); prose `string` → itself when under
+ * cap, else the REFUSAL prose; `{json}` → `JSON.stringify(x, null, 2)` when under
+ * cap, else the REFUSAL prose (no partial body).
+ */
+export declare function renderOpResultText(r: OpResult): string;
+/**
+ * The JSON VALUE for the CLI `--json` envelope `output` field, NOW BOUNDED at the
+ * 50KB read cap (TASK-013 / FGAP-015). Prose `string` → itself when under cap,
+ * else the REFUSAL string; `{read}` → its ReadStructured (already fail-closed —
+ * serializes tiny on over-cap); `{json}` → the raw value when under cap, else a
+ * fail-closed envelope that MIRRORS {@link ReadStructured}'s over-cap shape
+ * (`{ data: null, truncated: true, totalBytes, complete: false }`) so `--json`
+ * consumers see one uniform fail-closed envelope across `{read}` and bounded
+ * `{json}`. No partial payload is ever emitted past the cap.
+ */
+export declare function boundedJsonOutput(r: OpResult): unknown;
 export interface OpDefinition<P = any> {
     name: string;
     label: string;
     description: string;
     promptSnippet?: string;
     parameters: TSchema;
-    run(cwd: string, params: P): string | Promise<string>;
+    run(cwd: string, params: P, ctx?: DispatchContext): OpResult | Promise<OpResult>;
     authGated?: boolean;
     surface: "use" | "process";
 }
@@ -34,11 +74,147 @@ export declare const ops: OpDefinition[];
  * point; this list is the source of pi-context's contribution to it.
  */
 export declare const gatedTools: string[];
+/**
+ * One entry on the {@link INTENTIONALLY_UNEXPOSED_WRITERS} allowlist. `libraryFn`
+ * names a library write function deliberately NOT given its own op; exactly one
+ * of `safeOp` / `reason` carries the justification (`safeOp` when a safe op
+ * supersedes the raw writer; `reason` for internal/foreign-only writers with no
+ * op surface at all).
+ */
+export interface UnexposedWriter {
+    libraryFn: string;
+    reason?: string;
+    safeOp?: string;
+}
+/**
+ * The FGAP-009 non-exposure allowlist: every library write function that is
+ * deliberately NOT op-backed, with the reason it is withheld. This is the
+ * closure contract γ (TASK-008) WILL consume: γ's parity test — not yet written
+ * (no executable parity test exists in β; β defines the contract, γ implements
+ * the test against it) — WILL assert that EVERY library writer is either op-backed
+ * (appears in {@link ops}, directly or transitively) OR named here, so a
+ * newly-added library writer with neither an op nor an allowlist entry will fail
+ * that test, keeping the op surface and the library write surface in lockstep.
+ *
+ * The `*ForDir` twins of op-backed writers (e.g. `appendRelationForDir`,
+ * `writeRelationsForDir`, `upsertItemInBlockForDir`, `appendToBlockForDir`, …)
+ * are NOT enumerated individually: each is the dir-targeted internal twin of a
+ * cwd-form writer that IS op-backed, and is covered by that cwd-form op (the op
+ * resolves the active substrate dir then delegates to the same shared
+ * typed-file primitive the `*ForDir` twin calls). The contract is that γ's
+ * parity test (TASK-008, not yet written) WILL treat a `*ForDir` writer as
+ * covered when its cwd-form sibling is covered.
+ */
+export declare const INTENTIONALLY_UNEXPOSED_WRITERS: UnexposedWriter[];
+/**
+ * The five mutually-exhaustive ways a library write function is COVERED by the
+ * FGAP-009 op-surface ↔ library-write-surface parity contract. A writer that
+ * matches NONE of these is a silent gap that γ's (TASK-008) parity test — once
+ * written — MUST fail on. Coverage is the DISJUNCTION over these classes — a
+ * writer needs ANY one, not all.
+ */
+export declare enum CoverageClass {
+    /** An op's `run` calls the writer directly (e.g. `append-block-item` → `appendToBlock`). */
+    OpBackedDirect = "op-backed-direct",
+    /**
+     * An op's `run` reaches the writer TRANSITIVELY — through any helper / wrapper
+     * chain, not just a direct call. Two sub-shapes both land here:
+     *   - `*ByRef` / SDK relation porcelain: the `remove-relation` / `replace-relation`
+     *     / `append-relations` ops call `removeRelationByRef` / `replaceRelationByRef`
+     *     / `appendRelationsByRef`, which call `writeRelations`.
+     *   - init / switch → internal-helper chains: `context-init` → `initProject` →
+     *     `writeSkeletonConfig`; `context-switch` → `switchToExisting` /
+     *     `switchAndCreate` → `reconcileActiveSubstrateRegistration`. The writer is
+     *     not a `*ByRef` porcelain and is not allowlisted, but it IS reachable from an
+     *     op's `run` via a helper the op calls.
+     * Coverage condition: reachable from some op's `run` via any helper/wrapper chain.
+     */
+    OpBackedTransitive = "op-backed-transitive",
+    /**
+     * A `*ForDir` dir-targeted twin of a covered cwd-form writer (e.g.
+     * `appendToBlockForDir` is the twin of the op-backed `appendToBlock`). Covered
+     * by its cwd-form sibling — both delegate to the same shared typed-file
+     * primitive; the cwd-form op resolves the active dir then calls it.
+     */
+    ForDirTwin = "for-dir-twin",
+    /**
+     * On {@link INTENTIONALLY_UNEXPOSED_WRITERS}: a raw write deliberately given NO
+     * direct op (a scoped op supersedes it, or it is internal/foreign-only).
+     */
+    IntentionallyUnexposed = "intentionally-unexposed",
+    /**
+     * A block-api internal primitive below the op layer — the `*TypedFile` read/
+     * write layer (`readTypedFile` / `writeTypedFile`), `prepareItemIdentityForWrite`,
+     * and the identity / content-hash helpers. Never op-backed by design; the ops
+     * compose over these.
+     */
+    InternalPrimitive = "internal-primitive"
+}
+/**
+ * One clause of {@link OP_COVERAGE_RULE}: a coverage class plus the human-readable
+ * test γ applies to decide whether a writer falls in it.
+ */
+export interface CoverageClause {
+    coverageClass: CoverageClass;
+    test: string;
+}
+/**
+ * The FGAP-009 coverage RULE, made explicit so γ (TASK-008) will import the
+ * contract rather than re-derive it. A library write function is COVERED iff it
+ * matches ANY clause below (the disjunction); a writer matching none is a silent
+ * gap that γ's parity test — when written — MUST fail on. β fixes the contract
+ * here; no executable parity test exists yet (that is γ).
+ *
+ * Why `writeConfig` is allowlisted but `writeRelations` is NOT — the distinction
+ * a strict name-parity reading mis-saw as inconsistent:
+ *   - `writeConfig` has NO direct wholesale-config op. The scoped surface is
+ *     `amend-config` (one-entry-in-one-registry add/replace/remove, AJV-validated),
+ *     which deliberately does NOT expose a raw whole-config overwrite. So
+ *     `writeConfig` is `intentionally-unexposed` (the scoped op supersedes the raw
+ *     writer; a raw wholesale overwrite is withheld by design).
+ *   - `writeRelations` IS reached — transitively — by the relation ops:
+ *     `remove-relation` / `replace-relation` / `append-relations` call
+ *     `removeRelationByRef` / `replaceRelationByRef` / `appendRelationsByRef`, each
+ *     of which calls `writeRelations`. It is therefore `op-backed-transitive`
+ *     and needs NO allowlist entry. The asymmetry is real and correct: one writer
+ *     has an op path (via a helper/wrapper chain), the other does not.
+ *
+ * The `op-backed-transitive` clause covers BOTH the `*ByRef` relation porcelain
+ * AND the init/switch → internal-helper chains: `writeSkeletonConfig` (reached
+ * via `context-init` → `initProject`) and `reconcileActiveSubstrateRegistration`
+ * (reached via `context-switch` → `switchToExisting` / `switchAndCreate`) are
+ * neither `*ByRef` porcelain nor allowlisted, yet each is reachable from an op's
+ * `run` through a helper that op calls — so each classifies cleanly as
+ * `op-backed-transitive`, not as a gap.
+ */
+export declare const OP_COVERAGE_RULE: CoverageClause[];
+/**
+ * Build the DispatchContext threaded into an op's `run` from the in-pi tool
+ * execute boundary (registerAll). Two derivation branches:
+ *
+ *   - When `params.writer.user` is a non-empty string — the shape the
+ *     pi-agent-dispatch auth-gate stamps onto authGated op params on operator
+ *     confirm — the writer is a human identity. (The smuggle-ops promote-item /
+ *     write-schema-migration / context-switch carry a `writer` schema field
+ *     precisely so the gate has somewhere to stamp; this converts that field
+ *     into the contract ctx the op now consumes via its 3rd `run` arg.)
+ *   - Otherwise the writer is the running agent, identified by the active
+ *     model's id (`ExtensionContext.model.id`); falls back to "pi-agent" when
+ *     no model (or no id) is resolvable.
+ *
+ * Exported for unit testing — the two branches are asserted directly against
+ * synthetic params + a minimal ExtensionContext-shaped object.
+ */
+export declare function buildDispatchContextFromExecute(params: unknown, extCtx: {
+    model?: {
+        id?: string;
+    } | undefined;
+}): DispatchContext;
 /**
  * Register every op in `ops` as a pi tool. Each tool's execute body is the
- * uniform wrapper around the op's run(): coerce params, await run, place the
- * returned string at content[0].text. Behavior-identical to the prior inline
- * registrations.
+ * uniform wrapper around the op's run(): coerce params, build the attestation
+ * DispatchContext from the auth-gate-stamped writer (human) or the running
+ * model (agent), await run, place the returned string at content[0].text.
  */
 export declare function registerAll(pi: ExtensionAPI): void;
 //# sourceMappingURL=ops-registry.d.ts.map

package/dist/ops-registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ops-registry.d.ts","sourceRoot":"","sources":["../src/ops-registry.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAGX,YAAY,EAEZ,MAAM,iCAAiC,CAAC;AACzC,OAAO,EAAE,KAAK,OAAO,EAAQ,MAAM,SAAS,CAAC;AA4D7C;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,YAAY,CAAC,CAAC,GAAG,GAAG;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,UAAU,EAAE,OAAO,CAAC;IACpB,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,GAAG,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACtD,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,OAAO,EAAE,KAAK,GAAG,SAAS,CAAC;CAC3B;AA6BD,eAAO,MAAM,GAAG,EAAE,YAAY,EAuzC7B,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,UAAU,EAAE,MAAM,EAAsD,CAAC;AAYtF;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,EAAE,EAAE,YAAY,GAAG,IAAI,CAuBlD"}
+{"version":3,"file":"ops-registry.d.ts","sourceRoot":"","sources":["../src/ops-registry.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAGX,YAAY,EAEZ,MAAM,iCAAiC,CAAC;AACzC,OAAO,EAAE,KAAK,OAAO,EAAQ,MAAM,SAAS,CAAC;AAkC7C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAwB7D,OAAO,EAAe,KAAK,cAAc,EAAoC,MAAM,mBAAmB,CAAC;AAQvG;;;;;;;;;;;GAWG;AACH;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG;IAAE,IAAI,EAAE,OAAO,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,cAAc,CAAA;CAAE,CAAC;AA4C7E;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,QAAQ,GAAG,MAAM,CAStD;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,QAAQ,GAAG,OAAO,CAStD;AAED,MAAM,WAAW,YAAY,CAAC,CAAC,GAAG,GAAG;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,UAAU,EAAE,OAAO,CAAC;IACpB,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,EAAE,GAAG,CAAC,EAAE,eAAe,GAAG,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;IACjF,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,OAAO,EAAE,KAAK,GAAG,SAAS,CAAC;CAC3B;AA6BD,eAAO,MAAM,GAAG,EAAE,YAAY,EAmjD7B,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,UAAU,EAAE,MAAM,EAAsD,CAAC;AAEtF;;;;;;GAMG;AACH,MAAM,WAAW,eAAe;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,+BAA+B,EAAE,eAAe,EAgB5D,CAAC;AAEF;;;;;;GAMG;AACH,oBAAY,aAAa;IACxB,4FAA4F;IAC5F,cAAc,qBAAqB;IACnC;;;;;;;;;;;;OAYG;IACH,kBAAkB,yBAAyB;IAC3C;;;;;OAKG;IACH,UAAU,iBAAiB;IAC3B;;;OAGG;IACH,sBAAsB,4BAA4B;IAClD;;;;;OAKG;IACH,iBAAiB,uBAAuB;CACxC;AAED;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC9B,aAAa,EAAE,aAAa,CAAC;IAC7B,IAAI,EAAE,MAAM,CAAC;CACb;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,eAAO,MAAM,gBAAgB,EAAE,cAAc,EAqB5C,CAAC;AAYF;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,+BAA+B,CAC9C,MAAM,EAAE,OAAO,EACf,MAAM,EAAE;IAAE,KAAK,CAAC,EAAE;QAAE,EAAE,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,SAAS,CAAA;CAAE,GAC7C,eAAe,CAOjB;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,EAAE,EAAE,YAAY,GAAG,IAAI,CAwBlD"}