@shardworks/spider-apparatus 0.1.128 → 0.1.130

package/dist/engines/anima-session.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Anima-session engine — quick (Animator-backed).
+ *
+ * A generic reusable engine that summons an anima session. Unlike the other
+ * quick engines which embed prompt logic, anima-session receives all parameters
+ * through givens: role, prompt, cwd, and optionally conversationId and writ.
+ *
+ * Returns `{ status: 'launched', sessionId }` so the Spider's collect step
+ * can poll for completion on subsequent walks. Uses the generic default
+ * collect — no custom collect method.
+ */
+import type { EngineDesign } from '@shardworks/fabricator-apparatus';
+declare const animaSessionEngine: EngineDesign;
+export default animaSessionEngine;
+//# sourceMappingURL=anima-session.d.ts.map

package/dist/engines/anima-session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"anima-session.d.ts","sourceRoot":"","sources":["../../src/engines/anima-session.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kCAAkC,CAAC;AAIrE,QAAA,MAAM,kBAAkB,EAAE,YAgCzB,CAAC;AAEF,eAAe,kBAAkB,CAAC"}

package/dist/engines/anima-session.js

@@ -0,0 +1,43 @@
+/**
+ * Anima-session engine — quick (Animator-backed).
+ *
+ * A generic reusable engine that summons an anima session. Unlike the other
+ * quick engines which embed prompt logic, anima-session receives all parameters
+ * through givens: role, prompt, cwd, and optionally conversationId and writ.
+ *
+ * Returns `{ status: 'launched', sessionId }` so the Spider's collect step
+ * can poll for completion on subsequent walks. Uses the generic default
+ * collect — no custom collect method.
+ */
+import { guild } from '@shardworks/nexus-core';
+const animaSessionEngine = {
+    id: 'anima-session',
+    async run(givens, context) {
+        // Validate required givens
+        if (typeof givens.role !== 'string' || givens.role.length === 0) {
+            throw new Error('anima-session engine requires a non-empty string "role" given.');
+        }
+        if (typeof givens.prompt !== 'string' || givens.prompt.length === 0) {
+            throw new Error('anima-session engine requires a non-empty string "prompt" given.');
+        }
+        if (typeof givens.cwd !== 'string' || givens.cwd.length === 0) {
+            throw new Error('anima-session engine requires a non-empty string "cwd" given.');
+        }
+        const animator = guild().apparatus('animator');
+        const writ = givens.writ;
+        const handle = animator.summon({
+            role: givens.role,
+            prompt: givens.prompt,
+            cwd: givens.cwd,
+            ...(givens.conversationId ? { conversationId: givens.conversationId } : {}),
+            environment: writ ? { GIT_AUTHOR_EMAIL: `${writ.id}@nexus.local` } : {},
+            metadata: { engineId: context.engineId, ...(writ ? { writId: writ.id } : {}) },
+            // Enable streaming so the provider generates real-time chunks that the
+            // Animator's broadcaster captures for subscribeToSession() consumers.
+            streaming: true,
+        });
+        return { status: 'launched', sessionId: handle.sessionId };
+    },
+};
+export default animaSessionEngine;
+//# sourceMappingURL=anima-session.js.map

package/dist/engines/anima-session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"anima-session.js","sourceRoot":"","sources":["../../src/engines/anima-session.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,KAAK,EAAE,MAAM,wBAAwB,CAAC;AAK/C,MAAM,kBAAkB,GAAiB;IACvC,EAAE,EAAE,eAAe;IAEnB,KAAK,CAAC,GAAG,CAAC,MAAM,EAAE,OAAO;QACvB,2BAA2B;QAC3B,IAAI,OAAO,MAAM,CAAC,IAAI,KAAK,QAAQ,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAChE,MAAM,IAAI,KAAK,CAAC,gEAAgE,CAAC,CAAC;QACpF,CAAC;QACD,IAAI,OAAO,MAAM,CAAC,MAAM,KAAK,QAAQ,IAAI,MAAM,CAAC,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACpE,MAAM,IAAI,KAAK,CAAC,kEAAkE,CAAC,CAAC;QACtF,CAAC;QACD,IAAI,OAAO,MAAM,CAAC,GAAG,KAAK,QAAQ,IAAI,MAAM,CAAC,GAAG,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC9D,MAAM,IAAI,KAAK,CAAC,+DAA+D,CAAC,CAAC;QACnF,CAAC;QAED,MAAM,QAAQ,GAAG,KAAK,EAAE,CAAC,SAAS,CAAc,UAAU,CAAC,CAAC;QAC5D,MAAM,IAAI,GAAG,MAAM,CAAC,IAA2B,CAAC;QAEhD,MAAM,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC;YAC7B,IAAI,EAAE,MAAM,CAAC,IAAI;YACjB,MAAM,EAAE,MAAM,CAAC,MAAM;YACrB,GAAG,EAAE,MAAM,CAAC,GAAG;YACf,GAAG,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC,CAAC,EAAE,cAAc,EAAE,MAAM,CAAC,cAAwB,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACrF,WAAW,EAAE,IAAI,CAAC,CAAC,CAAC,EAAE,gBAAgB,EAAE,GAAG,IAAI,CAAC,EAAE,cAAc,EAAE,CAAC,CAAC,CAAC,EAAE;YACvE,QAAQ,EAAE,EAAE,QAAQ,EAAE,OAAO,CAAC,QAAQ,EAAE,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE;YAC9E,uEAAuE;YACvE,sEAAsE;YACtE,SAAS,EAAE,IAAI;SAChB,CAAC,CAAC;QAEH,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,CAAC,SAAS,EAAE,CAAC;IAC7D,CAAC;CACF,CAAC;AAEF,eAAe,kBAAkB,CAAC"}

package/dist/engines/index.d.ts

@@ -1,3 +1,4 @@
+export { default as animaSessionEngine } from './anima-session.ts';
 export { default as draftEngine } from './draft.ts';
 export { default as implementEngine } from './implement.ts';
 export { default as reviewEngine } from './review.ts';

package/dist/engines/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/engines/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,IAAI,WAAW,EAAE,MAAM,YAAY,CAAC;AACpD,OAAO,EAAE,OAAO,IAAI,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAC5D,OAAO,EAAE,OAAO,IAAI,YAAY,EAAE,MAAM,aAAa,CAAC;AACtD,OAAO,EAAE,OAAO,IAAI,YAAY,EAAE,MAAM,aAAa,CAAC;AACtD,OAAO,EAAE,OAAO,IAAI,UAAU,EAAE,MAAM,WAAW,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/engines/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,IAAI,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AACnE,OAAO,EAAE,OAAO,IAAI,WAAW,EAAE,MAAM,YAAY,CAAC;AACpD,OAAO,EAAE,OAAO,IAAI,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAC5D,OAAO,EAAE,OAAO,IAAI,YAAY,EAAE,MAAM,aAAa,CAAC;AACtD,OAAO,EAAE,OAAO,IAAI,YAAY,EAAE,MAAM,aAAa,CAAC;AACtD,OAAO,EAAE,OAAO,IAAI,UAAU,EAAE,MAAM,WAAW,CAAC"}

package/dist/engines/index.js

@@ -1,3 +1,4 @@
+export { default as animaSessionEngine } from "./anima-session.js";
 export { default as draftEngine } from "./draft.js";
 export { default as implementEngine } from "./implement.js";
 export { default as reviewEngine } from "./review.js";

package/dist/engines/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/engines/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,IAAI,WAAW,EAAE,MAAM,YAAY,CAAC;AACpD,OAAO,EAAE,OAAO,IAAI,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAC5D,OAAO,EAAE,OAAO,IAAI,YAAY,EAAE,MAAM,aAAa,CAAC;AACtD,OAAO,EAAE,OAAO,IAAI,YAAY,EAAE,MAAM,aAAa,CAAC;AACtD,OAAO,EAAE,OAAO,IAAI,UAAU,EAAE,MAAM,WAAW,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/engines/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,IAAI,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AACnE,OAAO,EAAE,OAAO,IAAI,WAAW,EAAE,MAAM,YAAY,CAAC;AACpD,OAAO,EAAE,OAAO,IAAI,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAC5D,OAAO,EAAE,OAAO,IAAI,YAAY,EAAE,MAAM,aAAa,CAAC;AACtD,OAAO,EAAE,OAAO,IAAI,YAAY,EAAE,MAAM,aAAa,CAAC;AACtD,OAAO,EAAE,OAAO,IAAI,UAAU,EAAE,MAAM,WAAW,CAAC"}

package/dist/engines/seal.d.ts

@@ -1,9 +1,14 @@
 /**
  * Seal engine — clockwork.
  *
- * Seals the draft binding via the Scriptorium. Reads the draft branch
+ * Closes a draft binding via the Scriptorium. Reads the draft branch
  * from context.upstream['draft'] (the DraftYields from the draft engine).
- * Returns SealYields with the sealed commit info.
+ *
+ * By default, seals the draft (merges inscriptions into the sealed binding)
+ * and returns SealYields with the sealed commit info. When the `abandon`
+ * given is truthy, abandons the draft instead — removing the worktree and
+ * branch without merging. This is used by rigs that need codebase access
+ * (e.g. planning rigs) but don't produce inscriptions to seal.
  */
 import type { EngineDesign } from '@shardworks/fabricator-apparatus';
 declare const sealEngine: EngineDesign;

package/dist/engines/seal.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"seal.d.ts","sourceRoot":"","sources":["../../src/engines/seal.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kCAAkC,CAAC;AAIrE,QAAA,MAAM,UAAU,EAAE,YAyBjB,CAAC;AAEF,eAAe,UAAU,CAAC"}
+{"version":3,"file":"seal.d.ts","sourceRoot":"","sources":["../../src/engines/seal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kCAAkC,CAAC;AAIrE,QAAA,MAAM,UAAU,EAAE,YAmCjB,CAAC;AAEF,eAAe,UAAU,CAAC"}

package/dist/engines/seal.js

@@ -1,19 +1,32 @@
 /**
  * Seal engine — clockwork.
  *
- * Seals the draft binding via the Scriptorium. Reads the draft branch
+ * Closes a draft binding via the Scriptorium. Reads the draft branch
  * from context.upstream['draft'] (the DraftYields from the draft engine).
- * Returns SealYields with the sealed commit info.
+ *
+ * By default, seals the draft (merges inscriptions into the sealed binding)
+ * and returns SealYields with the sealed commit info. When the `abandon`
+ * given is truthy, abandons the draft instead — removing the worktree and
+ * branch without merging. This is used by rigs that need codebase access
+ * (e.g. planning rigs) but don't produce inscriptions to seal.
  */
 import { guild } from '@shardworks/nexus-core';
 const sealEngine = {
     id: 'seal',
-    async run(_givens, context) {
+    async run(givens, context) {
         const scriptorium = guild().apparatus('codexes');
         const draftYields = context.upstream['draft'];
         if (!draftYields) {
             throw new Error('Seal engine requires draft yields in context.upstream but none found.');
         }
+        if (givens.abandon) {
+            await scriptorium.abandonDraft({
+                codexName: draftYields.codexName,
+                branch: draftYields.branch,
+                force: true,
+            });
+            return { status: 'completed', yields: { abandoned: true } };
+        }
         const result = await scriptorium.seal({
             codexName: draftYields.codexName,
             sourceBranch: draftYields.branch,

package/dist/engines/seal.js.map

@@ -1 +1 @@
-{"version":3,"file":"seal.js","sourceRoot":"","sources":["../../src/engines/seal.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,KAAK,EAAE,MAAM,wBAAwB,CAAC;AAK/C,MAAM,UAAU,GAAiB;IAC/B,EAAE,EAAE,MAAM;IAEV,KAAK,CAAC,GAAG,CAAC,OAAO,EAAE,OAAO;QACxB,MAAM,WAAW,GAAG,KAAK,EAAE,CAAC,SAAS,CAAiB,SAAS,CAAC,CAAC;QACjE,MAAM,WAAW,GAAG,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA4B,CAAC;QAEzE,IAAI,CAAC,WAAW,EAAE,CAAC;YACjB,MAAM,IAAI,KAAK,CAAC,uEAAuE,CAAC,CAAC;QAC3F,CAAC;QAED,MAAM,MAAM,GAAG,MAAM,WAAW,CAAC,IAAI,CAAC;YACpC,SAAS,EAAE,WAAW,CAAC,SAAS;YAChC,YAAY,EAAE,WAAW,CAAC,MAAM;SACjC,CAAC,CAAC;QAEH,MAAM,MAAM,GAAe;YACzB,YAAY,EAAE,MAAM,CAAC,YAAY;YACjC,QAAQ,EAAE,MAAM,CAAC,QAAQ;YACzB,OAAO,EAAE,MAAM,CAAC,OAAO;YACvB,kBAAkB,EAAE,MAAM,CAAC,kBAAkB;SAC9C,CAAC;QAEF,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,CAAC;IACzC,CAAC;CACF,CAAC;AAEF,eAAe,UAAU,CAAC"}
+{"version":3,"file":"seal.js","sourceRoot":"","sources":["../../src/engines/seal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,KAAK,EAAE,MAAM,wBAAwB,CAAC;AAK/C,MAAM,UAAU,GAAiB;IAC/B,EAAE,EAAE,MAAM;IAEV,KAAK,CAAC,GAAG,CAAC,MAAM,EAAE,OAAO;QACvB,MAAM,WAAW,GAAG,KAAK,EAAE,CAAC,SAAS,CAAiB,SAAS,CAAC,CAAC;QACjE,MAAM,WAAW,GAAG,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA4B,CAAC;QAEzE,IAAI,CAAC,WAAW,EAAE,CAAC;YACjB,MAAM,IAAI,KAAK,CAAC,uEAAuE,CAAC,CAAC;QAC3F,CAAC;QAED,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;YACnB,MAAM,WAAW,CAAC,YAAY,CAAC;gBAC7B,SAAS,EAAE,WAAW,CAAC,SAAS;gBAChC,MAAM,EAAE,WAAW,CAAC,MAAM;gBAC1B,KAAK,EAAE,IAAI;aACZ,CAAC,CAAC;YAEH,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,EAAE,CAAC;QAC9D,CAAC;QAED,MAAM,MAAM,GAAG,MAAM,WAAW,CAAC,IAAI,CAAC;YACpC,SAAS,EAAE,WAAW,CAAC,SAAS;YAChC,YAAY,EAAE,WAAW,CAAC,MAAM;SACjC,CAAC,CAAC;QAEH,MAAM,MAAM,GAAe;YACzB,YAAY,EAAE,MAAM,CAAC,YAAY;YACjC,QAAQ,EAAE,MAAM,CAAC,QAAQ;YACzB,OAAO,EAAE,MAAM,CAAC,OAAO;YACvB,kBAAkB,EAAE,MAAM,CAAC,kBAAkB;SAC9C,CAAC;QAEF,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,CAAC;IACzC,CAAC;CACF,CAAC;AAEF,eAAe,UAAU,CAAC"}

package/dist/index.d.ts

@@ -7,7 +7,8 @@
  * Public types (RigDoc, EngineInstance, CrawlResult, SpiderApi, etc.) are
  * re-exported for consumers that inspect walk results or rig state.
  */
-export type { EngineStatus, EngineInstance, RigStatus, RigDoc, RigFilters, CrawlResult, SpiderApi, SpiderConfig, BlockRecord, BlockType, CheckResult, DraftYields, SealYields, RigTemplate, RigTemplateEngine, InputRequestStatus, InputRequestDoc, ChoiceQuestionSpec, BooleanQuestionSpec, TextQuestionSpec, QuestionSpec, ChoiceAnswer, AnswerValue, } from './types.ts';
+export type { EngineStatus, EngineInstance, RigStatus, RigDoc, RigFilters, CrawlResult, SpiderApi, SpiderConfig, BlockRecord, BlockType, BlockTypeInfo, CheckResult, DraftYields, SealYields, RigTemplate, RigTemplateEngine, RigTemplateInfo, SpiderEngineRunResult, SpiderCollectResult, InputRequestStatus, InputRequestDoc, ChoiceQuestionSpec, BooleanQuestionSpec, TextQuestionSpec, QuestionSpec, ChoiceAnswer, AnswerValue, } from './types.ts';
+export type { SpiderKit } from './spider.ts';
 declare const _default: import("@shardworks/nexus-core").Plugin;
 export default _default;
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAMH,YAAY,EACV,YAAY,EACZ,cAAc,EACd,SAAS,EACT,MAAM,EACN,UAAU,EACV,WAAW,EACX,SAAS,EACT,YAAY,EACZ,WAAW,EACX,SAAS,EACT,WAAW,EACX,WAAW,EACX,UAAU,EACV,WAAW,EACX,iBAAiB,EACjB,kBAAkB,EAClB,eAAe,EACf,kBAAkB,EAClB,mBAAmB,EACnB,gBAAgB,EAChB,YAAY,EACZ,YAAY,EACZ,WAAW,GACZ,MAAM,YAAY,CAAC;;AAIpB,wBAA8B"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAMH,YAAY,EACV,YAAY,EACZ,cAAc,EACd,SAAS,EACT,MAAM,EACN,UAAU,EACV,WAAW,EACX,SAAS,EACT,YAAY,EACZ,WAAW,EACX,SAAS,EACT,aAAa,EACb,WAAW,EACX,WAAW,EACX,UAAU,EACV,WAAW,EACX,iBAAiB,EACjB,eAAe,EACf,qBAAqB,EACrB,mBAAmB,EACnB,kBAAkB,EAClB,eAAe,EACf,kBAAkB,EAClB,mBAAmB,EACnB,gBAAgB,EAChB,YAAY,EACZ,YAAY,EACZ,WAAW,GACZ,MAAM,YAAY,CAAC;AAEpB,YAAY,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;;AAI7C,wBAA8B"}

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AA8B3C,yEAAyE;AAEzE,eAAe,YAAY,EAAE,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAoC3C,yEAAyE;AAEzE,eAAe,YAAY,EAAE,CAAC"}

package/dist/oculus-routes.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Spider — custom Oculus API routes.
+ *
+ * Contributes:
+ * - GET /api/spider/config — aggregated snapshot of Spider config
+ * - GET /api/spider/session-transcript — session transcript and status
+ * - GET /api/spider/session-stream — SSE stream of real-time session chunks
+ *
+ * Does NOT import from @shardworks/oculus-apparatus to avoid a circular
+ * package dependency. The route shape is compatible with RouteContribution
+ * from the Oculus types.
+ */
+import type { Context } from 'hono';
+export declare const spiderRoutes: ({
+    method: string;
+    path: string;
+    handler: (c: Context) => Response & import("hono").TypedResponse<{
+        templates: {
+            name: string;
+            source: string;
+            template: {
+                engines: {
+                    id: string;
+                    designId: string;
+                    upstream?: string[] | undefined;
+                    givens?: {
+                        [x: string]: import("hono/utils/types").JSONValue;
+                    } | undefined;
+                    when?: string | undefined;
+                }[];
+                resolutionEngine?: string | undefined;
+            };
+        }[];
+        templateMappings: {
+            [x: string]: string;
+        };
+        engineDesigns: {
+            id: string;
+            pluginId: string;
+            hasCollect: boolean;
+        }[];
+        blockTypes: {
+            id: string;
+            pluginId: string;
+            pollIntervalMs?: number | undefined;
+        }[];
+    }, import("hono/utils/http-status").ContentfulStatusCode, "json">;
+} | {
+    method: string;
+    path: string;
+    handler: (c: Context) => Promise<Response>;
+})[];
+//# sourceMappingURL=oculus-routes.d.ts.map

package/dist/oculus-routes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"oculus-routes.d.ts","sourceRoot":"","sources":["../src/oculus-routes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AAepC,eAAO,MAAM,YAAY;;;iBAIR,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAiDD,OAAO;IAkF7B,CAAC"}

package/dist/oculus-routes.js

@@ -0,0 +1,133 @@
+/**
+ * Spider — custom Oculus API routes.
+ *
+ * Contributes:
+ * - GET /api/spider/config — aggregated snapshot of Spider config
+ * - GET /api/spider/session-transcript — session transcript and status
+ * - GET /api/spider/session-stream — SSE stream of real-time session chunks
+ *
+ * Does NOT import from @shardworks/oculus-apparatus to avoid a circular
+ * package dependency. The route shape is compatible with RouteContribution
+ * from the Oculus types.
+ */
+import { streamSSE } from 'hono/streaming';
+import { guild } from '@shardworks/nexus-core';
+export const spiderRoutes = [
+    {
+        method: 'GET',
+        path: '/api/spider/config',
+        handler: (c) => {
+            const g = guild();
+            const fabricator = g.apparatus('fabricator');
+            const spider = g.apparatus('spider');
+            return c.json({
+                templates: spider.listTemplates(),
+                templateMappings: spider.listTemplateMappings(),
+                engineDesigns: fabricator.listEngineDesigns(),
+                blockTypes: spider.listBlockTypes(),
+            });
+        },
+    },
+    {
+        method: 'GET',
+        path: '/api/spider/session-transcript',
+        handler: async (c) => {
+            const sessionId = c.req.query('sessionId');
+            if (!sessionId) {
+                return c.json({ error: 'sessionId is required' }, 400);
+            }
+            const g = guild();
+            const stacks = g.apparatus('stacks');
+            const sessionsBook = stacks.readBook('animator', 'sessions');
+            const session = await sessionsBook.get(sessionId);
+            if (!session) {
+                return c.json({ error: 'Session not found' }, 404);
+            }
+            if (session.status === 'running') {
+                return c.json({ messages: [], sessionStatus: 'running' });
+            }
+            const transcriptsBook = stacks.readBook('animator', 'transcripts');
+            const transcript = await transcriptsBook.get(sessionId);
+            return c.json({
+                messages: transcript?.messages ?? [],
+                sessionStatus: session.status,
+            });
+        },
+    },
+    {
+        method: 'GET',
+        path: '/api/spider/session-stream',
+        handler: async (c) => {
+            const sessionId = c.req.query('sessionId');
+            if (!sessionId) {
+                return c.json({ error: 'sessionId is required' }, 400);
+            }
+            const g = guild();
+            const stacks = g.apparatus('stacks');
+            const sessionsBook = stacks.readBook('animator', 'sessions');
+            const session = await sessionsBook.get(sessionId);
+            if (!session) {
+                return c.json({ error: 'Session not found' }, 404);
+            }
+            // For already-completed sessions, stream the full transcript and close.
+            if (session.status !== 'running') {
+                const transcriptsBook = stacks.readBook('animator', 'transcripts');
+                const transcript = await transcriptsBook.get(sessionId);
+                return streamSSE(c, async (stream) => {
+                    await stream.writeSSE({
+                        event: 'transcript',
+                        data: JSON.stringify({ messages: transcript?.messages ?? [] }),
+                    });
+                    await stream.writeSSE({
+                        event: 'done',
+                        data: JSON.stringify({ status: session.status }),
+                    });
+                });
+            }
+            // For running sessions, subscribe to the Animator's in-process broadcaster.
+            const animator = g.apparatus('animator');
+            const chunkStream = animator.subscribeToSession(sessionId);
+            if (!chunkStream) {
+                // The session is marked running in Stacks but has no in-memory broadcaster
+                // (e.g. a server restart happened). Return an empty stream so the UI can
+                // show a meaningful "no data" state and fall back gracefully.
+                return streamSSE(c, async (stream) => {
+                    await stream.writeSSE({
+                        event: 'done',
+                        data: JSON.stringify({ status: 'running', noStream: true }),
+                    });
+                });
+            }
+            return streamSSE(c, async (stream) => {
+                try {
+                    for await (const chunk of chunkStream) {
+                        await stream.writeSSE({
+                            event: 'chunk',
+                            data: JSON.stringify(chunk),
+                        });
+                    }
+                    // All chunks consumed — session has ended. Fetch and emit final transcript.
+                    const transcriptsBook = stacks.readBook('animator', 'transcripts');
+                    const transcript = await transcriptsBook.get(sessionId);
+                    await stream.writeSSE({
+                        event: 'transcript',
+                        data: JSON.stringify({ messages: transcript?.messages ?? [] }),
+                    });
+                    const finalSession = await sessionsBook.get(sessionId);
+                    await stream.writeSSE({
+                        event: 'done',
+                        data: JSON.stringify({ status: finalSession?.status ?? 'completed' }),
+                    });
+                }
+                catch (err) {
+                    const message = err instanceof Error ? err.message : String(err);
+                    await stream.writeSSE({
+                        event: 'error',
+                        data: JSON.stringify({ error: message }),
+                    });
+                }
+            });
+        },
+    },
+];
+//# sourceMappingURL=oculus-routes.js.map

package/dist/oculus-routes.js.map

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

package/dist/spider.d.ts

@@ -18,5 +18,13 @@
  * See: docs/architecture/apparatus/spider.md
  */
 import type { Plugin } from '@shardworks/nexus-core';
+import type { RigTemplate } from './types.ts';
+/** Kit contribution interface for the Spider's rig template system. */
+export interface SpiderKit {
+    /** Named rig templates. Keys are unqualified; registered as pluginId.key. */
+    rigTemplates?: Record<string, RigTemplate>;
+    /** Writ type → rig template name mappings. Keys are unqualified writ type names. */
+    rigTemplateMappings?: Record<string, string>;
+}
 export declare function createSpider(): Plugin;
 //# sourceMappingURL=spider.d.ts.map

package/dist/spider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"spider.d.ts","sourceRoot":"","sources":["../src/spider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAgC,MAAM,wBAAwB,CAAC;AA0VnF,wBAAgB,YAAY,IAAI,MAAM,CAonBrC"}
+{"version":3,"file":"spider.d.ts","sourceRoot":"","sources":["../src/spider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAwD,MAAM,wBAAwB,CAAC;AAO3G,OAAO,KAAK,EAWV,WAAW,EAIZ,MAAM,YAAY,CAAC;AAwCpB,uEAAuE;AACvE,MAAM,WAAW,SAAS;IACxB,6EAA6E;IAC7E,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IAC3C,oFAAoF;IACpF,mBAAmB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC9C;AAijCD,wBAAgB,YAAY,IAAI,MAAM,CA8xBrC"}