@opengeni/runtime 3.0.1 → 4.0.0-canary.35585322809001

package/dist/sandbox/provider-command-session.d.ts

@@ -1,6 +1,8 @@
-import type { SandboxProviderCommand } from "@opengeni/contracts";
+import type { SandboxProviderCommand, ModalRouterProviderCommand, CommandSupervisionReceipt } from "@opengeni/contracts";
 export type ProviderCommandOutput = {
     command: SandboxProviderCommand;
+    /** Exact read baseline for atomic byte-offset capture; absent for legacy pages. */
+    expected?: ModalRouterProviderCommand;
     chunks: Array<{
         stream: "stdout" | "stderr";
         chunkId: string;
@@ -12,20 +14,60 @@ export type ProviderCommandOutput = {
 /** These callbacks are supplied by the control plane after exact-route
  * retention/adoption. They are never accepted as command arguments. */
 export type ProviderCommandPersistence = {
+    rejectSupervisedLaunch?(command: ModalRouterProviderCommand): Promise<void>;
     load(): Promise<SandboxProviderCommand | null>;
     acknowledge(command: SandboxProviderCommand): Promise<SandboxProviderCommand>;
-    reserveInput(): Promise<number>;
+    reserveInput(byteLength?: number): Promise<number>;
+    recordSupervisionReceipt?(receipt: CommandSupervisionReceipt): Promise<void>;
+    loadSupervisionReceipt?(): Promise<CommandSupervisionReceipt | null>;
+    requestCancellation?(reason: "provider_deadline" | "explicit_stop"): Promise<void>;
+    cancellationRequested?(): Promise<boolean>;
+    captureRouterPage?(page: {
+        expected: ModalRouterProviderCommand;
+        command: ModalRouterProviderCommand;
+        stdout: string;
+        stderr: string;
+    }): Promise<{
+        command: ModalRouterProviderCommand;
+        captured: boolean;
+    }>;
 };
+export declare class ProviderCommandStartRejectedError extends Error {
+    constructor(cause: unknown);
+}
 export type ProviderCommandSession = {
+    verifyCommandSupervisionCapability?(): Promise<{
+        sandboxId: string;
+        taskId: string;
+    }>;
+    releaseSupervisedCommand?(handle: number): Promise<void>;
+    cancelSupervisedCommand?(handle: number, reason: "provider_deadline" | "explicit_stop"): Promise<boolean>;
     /** Abort only starts/initial observations still owned by this session call. */
     cancelPendingExecCommand?(): Promise<void>;
     getProviderCommand?(handle: number): SandboxProviderCommand | null;
     bindProviderCommand?(handle: number, command: SandboxProviderCommand, persistence: ProviderCommandPersistence): void;
     getProviderCommandOutput?(result: unknown): ProviderCommandOutput | null;
     acknowledgeCommandOutput?(result: string): Promise<void>;
+    /** Returns false for a legacy receipt. True means bytes and offsets committed
+     * together (or the page lost a cursor CAS and was safely discarded). */
+    captureCommandOutput?(result: string): Promise<boolean>;
+};
+export type PendingCommandSupervision = {
+    managed: boolean;
+};
+export declare function withPendingCommandSupervision<T>(state: PendingCommandSupervision | undefined, fn: () => T): T;
+/** Called only by the provider adapter before dispatching an idle supervisor. */
+export declare function markPendingCommandSupervised(): void;
+type SupervisedLaunchReservation = {
+    reserve(command: ModalRouterProviderCommand): Promise<void>;
 };
+export declare function withSupervisedLaunchReservation<T>(reservation: SupervisedLaunchReservation, fn: () => T): T;
+export declare function reserveSupervisedLaunch(command: ModalRouterProviderCommand): Promise<void>;
+export declare function withCommandSupervisionReady<T>(ready: boolean, fn: () => T): T;
+export declare function admittedCommandSupervisionReady(): boolean;
 export declare const MAX_PROVIDER_COMMAND_HANDLE = 2147483647;
 /** The alias is allocated by serialized workspace mutation admission, not by
  * an SDK instance or a process-writable counter. It remains route-scoped. */
 export declare function withProviderCommandHandle<T>(handle: number | undefined, fn: () => T): T;
 export declare function admittedProviderCommandHandle(): number | undefined;
+export {};

package/dist/sandbox/providers/modal-command-control.d.ts

@@ -1,38 +1,41 @@
-import { ModalClient } from "modal";
-import { SandboxProviderCommand } from "@opengeni/contracts";
+import { SandboxProviderCommand, CommandSupervisionReceipt, type ModalRouterProviderCommand } from "@opengeni/contracts";
 import type { ChannelAExecArgs } from "../channel-a.js";
-type CommandClient = Pick<ModalClient, "cpClient" | "version"> & Partial<Pick<ModalClient, "profile" | "logger">>;
-type GrpcMiddleware = NonNullable<NonNullable<ConstructorParameters<typeof ModalClient>[0]>["grpcMiddleware"]>[number];
-/** This dedicated command client never retries a request behind the caller's
- * back and preserves the exact cancellation signal, including streaming RPCs. */
-export declare const modalCommandAbortMiddleware: GrpcMiddleware;
-export type ModalCommandStream = "stdout" | "stderr";
+import type { ProviderCommandOutput } from "../provider-command-session.js";
+import { commandControlPlane } from "./modal-legacy-command-control.js";
+export { modalCommandAbortMiddleware } from "./modal-legacy-command-control.js";
 export type ModalProviderCommand = SandboxProviderCommand;
-export type ModalProviderOutputPage = {
-    command: ModalProviderCommand;
-    chunks: Array<{
-        stream: ModalCommandStream;
-        chunkId: string;
-        text: string;
-    }>;
-    exitCode: number | null;
-    streamFidelity: "separate" | "merged";
-};
-/** Version-pinned Modal control-plane boundary. Execution identity, output
- * batches and exit status come from authenticated provider RPCs, never sandbox
- * files or an SDK object's in-memory process map. Callers must store the
- * returned locator/cursors outside the command's write authority. */
+export type ModalProviderOutputPage = ProviderCommandOutput;
+type Client = Parameters<typeof commandControlPlane>[0];
+/** New commands use replayable task-router byte offsets. Legacy identifiers
+ * never cross that protocol boundary and are never used for new starts. */
 export declare class ModalCommandControl {
-    private readonly client;
     private readonly sandboxIdentity;
     private readonly root;
     private readonly environment;
+    private readonly routers;
+    private readonly client;
+    private readonly legacy;
+    private closed;
     private constructor();
-    static forSandbox(client: CommandClient, sandboxId: string | (() => string), root: string, environment?: Record<string, string> | (() => Record<string, string>)): ModalCommandControl;
+    static forSandbox(client: Client, sandboxId: string | (() => string), root: string, environment?: Record<string, string> | (() => Record<string, string>)): ModalCommandControl;
     private get sandboxId();
-    start(args: ChannelAExecArgs, signal?: AbortSignal): Promise<ModalProviderCommand>;
-    read(command: ModalProviderCommand, yieldTimeMs: number, signal?: AbortSignal): Promise<ModalProviderOutputPage>;
-    write(command: ModalProviderCommand, chars: string, messageIndex: number): Promise<void>;
-    private assertIdentity;
+    private withRouter;
+    close(): Promise<void>;
+    start(args: ChannelAExecArgs, signal?: AbortSignal): Promise<ModalRouterProviderCommand>;
+    /** Read-only, authenticated control execution on this exact instance. Never
+     * inferred from a fleet image selector or user command stdout. No cache: warm
+     * instances and route/task replacement must each pass before admission. */
+    verifySupervisionCapability(): Promise<{
+        sandboxId: string;
+        taskId: string;
+    }>;
+    /** Separate authenticated provider execution of the installed control helper.
+     * User command streams are never inspected for control evidence. */
+    supervisionControl(command: ModalRouterProviderCommand, action: "release" | "cancel" | "status" | "ack", receiptId?: string): Promise<{
+        state: "idle" | "running" | "quiescent";
+        receipt?: CommandSupervisionReceipt;
+    }>;
+    read(command: ModalProviderCommand, waitMs: number, signal?: AbortSignal): Promise<ModalProviderOutputPage>;
+    readProbe(command: ModalProviderCommand, waitMs: number, cancellation: AbortController): Promise<ModalProviderOutputPage>;
+    write(command: ModalProviderCommand, chars: string, index: number): Promise<void>;
 }
-export {};

package/dist/sandbox/providers/modal-command-router-wire.d.ts

@@ -0,0 +1,49 @@
+import protobuf from "protobufjs";
+import { ProviderCommandStartRejectedError } from "../provider-command-session.js";
+export declare const modalRouterWire: protobuf.Root;
+/** Only constructed at the authenticated Start RPC boundary. Transport loss,
+ * deadline, cancellation and UNKNOWN are deliberately not rejection proof. */
+export declare class ModalCommandStartRejectedError extends ProviderCommandStartRejectedError {
+    readonly code: number;
+    constructor(code: number, cause: unknown);
+}
+export type ModalRouterIdentity = {
+    taskId: string;
+    execId: string;
+};
+export type ModalRouterAccess = {
+    url: string;
+    jwt: string;
+};
+export type ModalRouterStart = ModalRouterIdentity & {
+    commandArgs: string[];
+    workdir: string;
+    env: Record<string, string>;
+    ptyInfo?: {
+        enabled: boolean;
+        winszRows: number;
+        winszCols: number;
+        envTerm: string;
+        ptyType: number;
+        noTerminateOnIdleStdin: boolean;
+    };
+};
+/** A single authenticated transport, owned and closed by its command adapter.
+ * Reads may stop at a byte boundary because the next read resumes at that exact
+ * offset. Mutations are never retried by this layer, including ambiguous starts.
+ */
+export declare class ModalCommandRouterWire {
+    private readonly client;
+    private readonly metadata;
+    private closed;
+    constructor(access: ModalRouterAccess, trustedRoots?: Buffer);
+    close(): void;
+    private unary;
+    start(request: ModalRouterStart, signal?: AbortSignal): Promise<void>;
+    write(identity: ModalRouterIdentity, offset: number, data: Uint8Array, signal?: AbortSignal): Promise<void>;
+    poll(identity: ModalRouterIdentity, signal?: AbortSignal): Promise<number | null>;
+    read(identity: ModalRouterIdentity, stream: "stdout" | "stderr", offset: number, waitMs: number, signal?: AbortSignal): Promise<{
+        bytes: Buffer;
+        eof: boolean;
+    }>;
+}

package/dist/sandbox/providers/modal-command-session.d.ts

@@ -7,4 +7,5 @@ import type { ModalCommandControl } from "./modal-command-control.js";
 export declare function installModalCommandSession(session: ProviderCommandSession & {
     execCommand?: ChannelASession["execCommand"];
     writeStdin?: ChannelASession["writeStdin"];
-}, control: ModalCommandControl): void;
+    verifyMaterializedPath?: (path: string, workdir: string) => Promise<void>;
+}, control: Pick<ModalCommandControl, "start" | "read" | "readProbe" | "write"> & Partial<Pick<ModalCommandControl, "supervisionControl" | "verifySupervisionCapability">>): void;

package/dist/sandbox/providers/modal-legacy-command-control.d.ts

@@ -0,0 +1,50 @@
+import { ModalClient } from "modal";
+import { ModalLegacyProviderCommand } from "@opengeni/contracts";
+import type { ChannelAExecArgs } from "../channel-a.js";
+type ControlPlane = Pick<ModalClient["cpClient"], "sandboxGetTaskId" | "containerExec" | "containerExecGetOutput" | "containerExecPutInput" | "taskGetCommandRouterAccess">;
+type CommandClient = Pick<ModalClient, "cpClient" | "version"> & Partial<Pick<ModalClient, "profile" | "logger">>;
+type GrpcMiddleware = NonNullable<NonNullable<ConstructorParameters<typeof ModalClient>[0]>["grpcMiddleware"]>[number];
+/** This dedicated command client never retries a request behind the caller's
+ * back and preserves the exact cancellation signal, including streaming RPCs. */
+export declare const modalCommandAbortMiddleware: GrpcMiddleware;
+export declare function commandControlPlane(client: CommandClient): ControlPlane;
+export type ModalCommandStream = "stdout" | "stderr";
+export type ModalProviderCommand = ModalLegacyProviderCommand;
+export type ModalProviderOutputPage = {
+    command: ModalProviderCommand;
+    chunks: Array<{
+        stream: ModalCommandStream;
+        chunkId: string;
+        text: string;
+    }>;
+    exitCode: number | null;
+    streamFidelity: "separate" | "merged";
+};
+export declare function decodePage(prior: string, input: Uint8Array[], terminal: boolean): {
+    text: string;
+    remainder: string;
+};
+/** Version-pinned Modal control-plane boundary. Execution identity, output
+ * batches and exit status come from authenticated provider RPCs, never sandbox
+ * files or an SDK object's in-memory process map. Callers must store the
+ * returned locator/cursors outside the command's write authority. */
+export declare class ModalCommandControl {
+    private readonly client;
+    private readonly sandboxIdentity;
+    private readonly root;
+    private readonly environment;
+    private constructor();
+    static forSandbox(client: CommandClient, sandboxId: string | (() => string), root: string, environment?: Record<string, string> | (() => Record<string, string>)): ModalCommandControl;
+    private get sandboxId();
+    start(args: ChannelAExecArgs, signal?: AbortSignal): Promise<ModalProviderCommand>;
+    read(command: ModalProviderCommand, yieldTimeMs: number, signal?: AbortSignal): Promise<ModalProviderOutputPage>;
+    /** Fixed internal probes own their cancellation controller and must drain
+     * both reads before relinquishing the surrounding provider-operation gate.
+     * Retained-command readers keep their existing signal/receipt contract.
+     */
+    readProbe(command: ModalProviderCommand, yieldTimeMs: number, cancellation: AbortController): Promise<ModalProviderOutputPage>;
+    private readOutput;
+    write(command: ModalProviderCommand, chars: string, messageIndex: number): Promise<void>;
+    private assertIdentity;
+}
+export {};

package/dist/sandbox/providers/modal-materialization-verification.d.ts

@@ -0,0 +1,7 @@
+import type { ModalCommandControl } from "./modal-command-control.js";
+/** A fixed read-only probe, not an admitted user command. Advance its private
+ * provider cursor locally; never borrow the surrounding mutation's retained
+ * handle or relax retained-command persistence requirements. The caller keeps
+ * the original backend and provider-operation gate for the entire observation.
+ */
+export declare function verifyModalMaterializedPath(control: Pick<ModalCommandControl, "start" | "readProbe">, path: string, workdir: string, pending: Set<AbortController>, observationTimeoutMs?: number): Promise<void>;

package/dist/sandbox/providers/modal.d.ts

@@ -58,14 +58,6 @@ type ModalModule = typeof import("modal");
 type ModalClientLike = InstanceType<ModalModule["ModalClient"]>;
 /** Loader seam so unit tests can inject a fake modal module. */
 export type ModalModuleLoader = () => Promise<Pick<ModalModule, "ModalClient">>;
-/**
- * Resolve + cache the private-registry Modal image. No-op unless BOTH
- * `modalImageRef` and `modalImageRegistrySecret` are set. Memoized per
- * (imageRef, secret, environment) so it runs once per worker process. Awaited at
- * worker boot for the deployment-global image and at turn time for pack-scoped
- * images BEFORE the first sandbox using that ref is created; `build` then reads the
- * resolved image and otherwise falls back to the public `fromTag` path.
- */
 export declare function ensureModalRegistryImage(settings: Settings, loadModal?: ModalModuleLoader): Promise<void>;
 /**
  * Choose the image selector for a Modal sandbox client from settings. Returns:

package/dist/sandbox/routing/routing-session.d.ts

@@ -1,6 +1,7 @@
 import type { ExposedPortEndpoint } from "../stream-port.js";
 import { type ProviderCommandPersistence, type ProviderCommandSession } from "../provider-command-session.js";
 import type { SandboxProviderCommand } from "@opengeni/contracts";
+import { type MaterializationFailureReason } from "../materialization-verification-error.js";
 import type { ChannelAExecArgs, ChannelAExecResult, ChannelARoutedWorkspaceImportBatchRequest, ChannelARoutedWorkspaceImportRequest, WorkspaceFileImportReceipt } from "../channel-a.js";
 /** The per-session active-sandbox pointer the proxy re-reads on every op. Mirror
  *  of `@opengeni/db`'s `ActiveSandboxPointer` (structural, so the leaf does not
@@ -42,6 +43,8 @@ export interface RoutableBackendSession extends ProviderCommandSession {
     pathExists?(path: string, runAs?: string): Promise<boolean>;
     viewImage?(args: unknown): Promise<unknown>;
     materializeEntry?(args: unknown): Promise<void>;
+    /** Provider-owned fixed read-only probe; never an agent command surface. */
+    verifyMaterializedPath?(path: string, workdir: string): Promise<void>;
     supportsPty?(): boolean;
     resolveExposedPort?(port: number): Promise<ExposedPortEndpoint>;
     serializeSessionState?(): Promise<unknown>;
@@ -109,6 +112,7 @@ export type RoutingRetainedProcessTerminalProof = {
 };
 export interface RoutingSandboxSessionDeps {
     providerCommandHandle?: (admission: unknown) => number | undefined;
+    providerSupervisionReady?: () => Promise<boolean>;
     providerCommandPersistence?: (process: RoutingRetainedProcess) => ProviderCommandPersistence;
     /**
      * The DEFAULT backend resolved at construction time (the same shape `resolve()`
@@ -148,6 +152,8 @@ export interface RoutingSandboxSessionDeps {
      * diagnostic only: callback failures are isolated and can never change the
      * provider result or durable mutation-settlement ordering. */
     onOperation?: RoutingSandboxOperationObserver;
+    /** Capture gates are not physical provider calls; observe every wait separately. */
+    onCaptureWait?: RoutingSandboxCaptureWaitObserver;
     /** Observe the first complete routed operation and only the subphases that
      * actually ran. Child durations are exclusive; capture waits are removed
      * from their enclosing admission/provider spans. */
@@ -238,8 +244,16 @@ export type RoutingSandboxOperationObservation = {
     op: string;
     outcome: "ok" | "not_found" | "failed";
     durationMs: number;
+    materializationFailureReason?: MaterializationFailureReason;
 };
 export type RoutingSandboxOperationObserver = (observation: RoutingSandboxOperationObservation) => void;
+export type RoutingSandboxCaptureWaitObserver = (observation: {
+    backend: string;
+    op: string;
+    outcome: "ok" | "failed";
+    durationMs: number;
+    captureWaitStage: "admission" | "provider";
+}) => void;
 export type RoutingSandboxPhaseOutcome = "completed" | "failed";
 export type RoutingSandboxWaitObservation = {
     durationMs: number;
@@ -351,6 +365,7 @@ export declare class RoutingSandboxSession implements RoutableBackendSession {
     private cachedEpoch;
     private cachedSandboxId;
     private cached;
+    private readonly homeResolutions;
     private lastResolved;
     /** Claimed synchronously before the first dispatch awaits, so concurrent
      * callers cannot emit duplicate first-operation observations. */
@@ -398,6 +413,7 @@ export declare class RoutingSandboxSession implements RoutableBackendSession {
      * is THE per-call re-read that makes a mid-turn swap land on the next op.
      */
     private resolve;
+    private resolvePointer;
     private invalidate;
     private registerRetainedProcess;
     private bindRetainedProviderCommand;
@@ -430,7 +446,11 @@ export declare class RoutingSandboxSession implements RoutableBackendSession {
      * race).
      */
     private dispatch;
+    /** Classify loss on the copied backend, including read-only preflight. This
+     * path never admits work or retries the failed operation on a new route. */
+    private throwProviderError;
     private dispatchWithRetries;
+    private observeCaptureWait;
     private invokeProviderOperation;
     /**
      * The failure-visibility boundary for the `exec_command` SDK capability tool — the
@@ -486,6 +506,7 @@ export declare class RoutingSandboxSession implements RoutableBackendSession {
      * the process backend and may prove terminal state, but never advance the
      * workspace generation. */
     writeStdinForProcessControl(args: unknown): Promise<string>;
+    cancelSupervisedCommand(providerSessionId: number, reason: "provider_deadline" | "explicit_stop"): Promise<boolean>;
     /** Empty-input eager reads belong to the model's foreground wait, while
      * cancellation/drain reads use the non-observing control method above. */
     writeStdinForProcessRead(args: unknown): Promise<string>;

package/dist/sandbox/turn-tool-cancellation.d.ts

@@ -17,6 +17,7 @@ type CommandCancellationSession = {
     retainedProcessIdentity?(providerSessionId: number): {
         id: string;
     } | null;
+    cancelSupervisedCommand?(providerSessionId: number, reason: "explicit_stop"): Promise<boolean>;
     writeStdinForProcessRead?(args: {
         sessionId: number;
         chars?: string;

package/dist/skill-library.d.ts

@@ -88,12 +88,6 @@ export declare function readSkillLibraryArtifact(root: string): SkillLibraryArti
  * the same canonical path and whole-artifact digest rules.
  */
 export declare function buildPortableSkillArtifact(inputFiles: readonly SkillLibraryFile[]): PortableSkillArtifact;
-/**
- * Canonical whole-artifact identity for any validated runtime Skill shape.
- * This deliberately does not require frontmatter because legacy Pack/session
- * contracts historically allowed a top-level SKILL.md without metadata. The
- * content identity is nevertheless byte-exact and shared with portable imports.
- */
 export declare function skillArtifactContentSha256(inputFiles: readonly SkillLibraryFile[]): string;
 /** Verify a reviewed artifact against its immutable catalog digest. */
 export declare function verifySkillLibraryArtifact(root: string, expectedSha256: string, entry?: Pick<SkillLibraryEntry, "id" | "version">): SkillLibraryArtifact;

package/dist/skill-library.js

@@ -20,7 +20,7 @@ import {
   skillArtifactContentSha256,
   skillLibraryRepositoryUrl,
   verifySkillLibraryArtifact
-} from "./chunk-GB763TSV.js";
+} from "./chunk-TE27J65Q.js";
 import "./chunk-PZ5AY32C.js";
 export {
   SKILL_MAX_FILES as PORTABLE_SKILL_MAX_FILES,

package/dist/workspace-tool-gateway.js

@@ -1,11 +1,13 @@
 import {
   prepareAgentTools
-} from "./chunk-RIJ6DCYS.js";
-import "./chunk-46BFUGFL.js";
-import "./chunk-FHGLYLBL.js";
-import "./chunk-GB763TSV.js";
+} from "./chunk-HCGLD7NH.js";
+import "./chunk-WIHICNWS.js";
+import "./chunk-SPT3PLMX.js";
+import "./chunk-4A4XTKKX.js";
+import "./chunk-ZG2YH25H.js";
+import "./chunk-TE27J65Q.js";
 import "./chunk-UZ66CGC2.js";
-import "./chunk-UU6EJR52.js";
+import "./chunk-YU4VRTR4.js";
 import "./chunk-UNICCRW5.js";
 import "./chunk-PZ5AY32C.js";
 export {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opengeni/runtime",
-  "version": "3.0.1",
+  "version": "4.0.0-canary.35585322809001",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
@@ -57,24 +57,26 @@
   },
   "dependencies": {
     "@alibaba-group/opensandbox": "0.1.11",
+    "@grpc/grpc-js": "1.14.4",
     "@modelcontextprotocol/sdk": "1.29.0",
     "@noble/hashes": "^1.8.0",
     "@openai/agents": "0.14.3",
     "@openai/agents-core": "0.14.3",
     "@openai/agents-extensions": "0.14.3",
-    "@opengeni/agent-proto": "^0.6.0",
-    "@opengeni/capabilities": "^0.3.4",
-    "@opengeni/codemode": "^0.5.9",
-    "@opengeni/codex": "^0.2.23",
-    "@opengeni/config": "^1.2.2",
-    "@opengeni/contracts": "^4.1.0",
-    "@opengeni/network": "^0.3.1",
-    "@opengeni/sdk": "^6.1.0",
-    "@opengeni/tool-gateway": "^0.1.10",
-    "@opengeni/xai-subscription": "^0.1.4",
+    "@opengeni/agent-proto": "^0.6.0-canary.35585322809001",
+    "@opengeni/capabilities": "^0.3.4-canary.35585322809001",
+    "@opengeni/codemode": "^0.6.0-canary.35585322809001",
+    "@opengeni/codex": "^0.2.24-canary.35585322809001",
+    "@opengeni/config": "^2.0.0-canary.35585322809001",
+    "@opengeni/contracts": "^5.0.0-canary.35585322809001",
+    "@opengeni/network": "^0.3.1-canary.35585322809001",
+    "@opengeni/sdk": "^7.0.0-canary.35585322809001",
+    "@opengeni/tool-gateway": "^0.1.11-canary.35585322809001",
+    "@opengeni/xai-subscription": "^0.1.4-canary.35585322809001",
     "debug": "4.4.3",
     "modal": "0.9.0",
     "openai": "6.47.0",
+    "protobufjs": "7.6.5",
     "ws": "8.21.1",
     "zod": "4.4.3"
   }

package/src/bundled_artifact_skills/opengeni-documents/SKILL.md

@@ -10,6 +10,14 @@ live object the user sees in the Artifacts dock and full editor. Never create a
 mutable DOCX shadow, publish a sandbox file, or alternate between file and
 artifact state.
 
+This also applies when a report is a secondary output of another task, such as
+a Knowledge cleanup audit. Declare the report through the available goal tools
+before authoring; if the task has no goal and goal tools are available, create
+one with the report requirement. If a goal already exists, append the report
+requirement without replacing the standing objective. Ordinary chat answers,
+brief progress updates, internal worker findings, code navigation and explicitly requested local-file
+work are not report deliverables.
+
 Read [references/api.md](references/api.md) before editing.
 When using `skill_read`, request that relative path from this Skill; reading
 does not materialize a local folder. Use an existing local copy only when the
@@ -63,8 +71,19 @@ Skill was installed or explicitly checked out to the filesystem.
 
 ## Completion gate
 
+- Every declared report requirement has server-verified artifact delivery
+  evidence at goal completion. Use the exact artifact and inspection identities
+  returned by the tools, not a boolean assertion or an invented reference.
 - The requested result exists in the durable artifact, not merely a local file.
 - Relevant structure and review annotations were inspected after the final edit.
+- Report completion needs a final `body` inspection receipt; `summary` alone
+  does not qualify. Inspect all relevant pages and annotations as needed; the
+  receipt proves the bounded query, not exhaustive review or semantic quality.
 - Any requested export completed and its `fileId`, format, and pinned source
   head were reported.
 - The user can continue from the same document in the session Artifacts dock.
+- Include the returned artifact reference in the handoff. A sandbox path, raw
+  file ID, or separately published Markdown/DOCX file does not replace the native
+  document. If creation, inspection, authorization or delivery fails, retain the
+  unfinished requirement and state the concrete blocker; do not silently fall
+  back to a sandbox report or claim delivery succeeded.

package/src/bundled_artifact_skills/opengeni-documents/references/api.md

@@ -17,6 +17,28 @@ automatically.
 For a direct `opengeni__editable_artifact_inspect` call, pass the query below as
 `request`, alongside `artifactId` and `modality: "document"`.
 
+## Report requirements and inspection evidence
+
+For a report deliverable, declare `reportRequirements: [{ id: "audit", title:
+"Knowledge organization audit" }]` through `goal_set` when creating a goal, or
+through `goal_progress` alongside its progress note and idempotency key for an
+existing active goal. Keep requirement IDs stable; do not replace the objective
+merely to add a report. Ordinary answers and internal worker findings need no
+report requirement.
+
+After the final edit, inspect the relevant document body using a `body` query;
+a `summary` query alone does not satisfy report completion. Inspect additional
+pages and annotations as needed—the receipt proves only the bounded query, not
+exhaustive review or content quality. The direct result
+and `document.inspect(...)` return `inspectionReceiptId` when the server records
+verified document inspection. Pass `reportDeliveries: [{ requirementId: "audit",
+artifactId: document.id, inspectionReceiptId }]` with the completion evidence to
+`goal_complete`. Missing proof is not a successful delivery; never fabricate it.
+If the document changes, inspect it again and use the new receipt. Include the
+returned artifact reference in the user handoff.
+
+## Authoring example
+
 ```js
 import { openGeni } from "@opengeni/codemode";