rhachet 1.17.0 → 1.19.0

package/dist/domain.operations/context/findBrainAtomByRef.d.ts

@@ -0,0 +1,10 @@
+import type { RefByUnique } from 'domain-objects';
+import type { BrainAtom } from '../../domain.objects/BrainAtom';
+/**
+ * .what = finds a brain atom by its unique reference
+ * .why = enables lookup of registered atoms by { repo, slug }
+ */
+export declare const findBrainAtomByRef: (input: {
+    atoms: BrainAtom[];
+    ref: RefByUnique<typeof BrainAtom>;
+}) => BrainAtom;

package/dist/domain.operations/context/findBrainAtomByRef.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.findBrainAtomByRef = void 0;
+const helpful_errors_1 = require("helpful-errors");
+/**
+ * .what = finds a brain atom by its unique reference
+ * .why = enables lookup of registered atoms by { repo, slug }
+ */
+const findBrainAtomByRef = (input) => {
+    // fail fast if no atoms available
+    if (input.atoms.length === 0)
+        throw new helpful_errors_1.BadRequestError('no atoms available in context', {
+            ref: input.ref,
+        });
+    // lookup atom by ref
+    const atomFound = input.atoms.find((a) => a.repo === input.ref.repo && a.slug === input.ref.slug);
+    // fail if not found
+    if (!atomFound)
+        throw new helpful_errors_1.BadRequestError('brain atom not found', { ref: input.ref });
+    return atomFound;
+};
+exports.findBrainAtomByRef = findBrainAtomByRef;
+//# sourceMappingURL=findBrainAtomByRef.js.map

package/dist/domain.operations/context/findBrainAtomByRef.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"findBrainAtomByRef.js","sourceRoot":"","sources":["../../../src/domain.operations/context/findBrainAtomByRef.ts"],"names":[],"mappings":";;;AACA,mDAAiD;AAIjD;;;GAGG;AACI,MAAM,kBAAkB,GAAG,CAAC,KAGlC,EAAa,EAAE;IACd,kCAAkC;IAClC,IAAI,KAAK,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC;QAC1B,MAAM,IAAI,gCAAe,CAAC,+BAA+B,EAAE;YACzD,GAAG,EAAE,KAAK,CAAC,GAAG;SACf,CAAC,CAAC;IAEL,qBAAqB;IACrB,MAAM,SAAS,GAAG,KAAK,CAAC,KAAK,CAAC,IAAI,CAChC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,KAAK,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC,CAAC,IAAI,KAAK,KAAK,CAAC,GAAG,CAAC,IAAI,CAC9D,CAAC;IAEF,oBAAoB;IACpB,IAAI,CAAC,SAAS;QACZ,MAAM,IAAI,gCAAe,CAAC,sBAAsB,EAAE,EAAE,GAAG,EAAE,KAAK,CAAC,GAAG,EAAE,CAAC,CAAC;IAExE,OAAO,SAAS,CAAC;AACnB,CAAC,CAAC;AApBW,QAAA,kBAAkB,sBAoB7B"}

package/dist/domain.operations/context/findBrainReplByRef.d.ts

@@ -0,0 +1,10 @@
+import type { RefByUnique } from 'domain-objects';
+import type { BrainRepl } from '../../domain.objects/BrainRepl';
+/**
+ * .what = finds a brain repl by its unique reference
+ * .why = enables lookup of registered repls by { repo, slug }
+ */
+export declare const findBrainReplByRef: (input: {
+    repls: BrainRepl[];
+    ref: RefByUnique<typeof BrainRepl>;
+}) => BrainRepl;

package/dist/domain.operations/context/findBrainReplByRef.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.findBrainReplByRef = void 0;
+const helpful_errors_1 = require("helpful-errors");
+/**
+ * .what = finds a brain repl by its unique reference
+ * .why = enables lookup of registered repls by { repo, slug }
+ */
+const findBrainReplByRef = (input) => {
+    // fail fast if no repls available
+    if (input.repls.length === 0)
+        throw new helpful_errors_1.BadRequestError('no repls available in context', {
+            ref: input.ref,
+        });
+    // lookup repl by ref
+    const replFound = input.repls.find((r) => r.repo === input.ref.repo && r.slug === input.ref.slug);
+    // fail if not found
+    if (!replFound)
+        throw new helpful_errors_1.BadRequestError('brain repl not found', { ref: input.ref });
+    return replFound;
+};
+exports.findBrainReplByRef = findBrainReplByRef;
+//# sourceMappingURL=findBrainReplByRef.js.map

package/dist/domain.operations/context/findBrainReplByRef.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"findBrainReplByRef.js","sourceRoot":"","sources":["../../../src/domain.operations/context/findBrainReplByRef.ts"],"names":[],"mappings":";;;AACA,mDAAiD;AAIjD;;;GAGG;AACI,MAAM,kBAAkB,GAAG,CAAC,KAGlC,EAAa,EAAE;IACd,kCAAkC;IAClC,IAAI,KAAK,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC;QAC1B,MAAM,IAAI,gCAAe,CAAC,+BAA+B,EAAE;YACzD,GAAG,EAAE,KAAK,CAAC,GAAG;SACf,CAAC,CAAC;IAEL,qBAAqB;IACrB,MAAM,SAAS,GAAG,KAAK,CAAC,KAAK,CAAC,IAAI,CAChC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,KAAK,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC,CAAC,IAAI,KAAK,KAAK,CAAC,GAAG,CAAC,IAAI,CAC9D,CAAC;IAEF,oBAAoB;IACpB,IAAI,CAAC,SAAS;QACZ,MAAM,IAAI,gCAAe,CAAC,sBAAsB,EAAE,EAAE,GAAG,EAAE,KAAK,CAAC,GAAG,EAAE,CAAC,CAAC;IAExE,OAAO,SAAS,CAAC;AACnB,CAAC,CAAC;AApBW,QAAA,kBAAkB,sBAoB7B"}

package/dist/domain.operations/context/genContextBrain.d.ts

@@ -0,0 +1,14 @@
+import type { BrainAtom } from '../../domain.objects/BrainAtom';
+import type { BrainRepl } from '../../domain.objects/BrainRepl';
+import type { ContextBrain } from '../../domain.objects/ContextBrain';
+/**
+ * .what = factory to create a brain context from plugin-provided atoms and repls
+ * .why =
+ *   - provides a clean entry point for context creation
+ *   - validates no duplicate { repo, slug } identifiers
+ *   - composes the context with lookup and delegation logic
+ */
+export declare const genContextBrain: (input: {
+    atoms?: BrainAtom[];
+    repls?: BrainRepl[];
+}) => ContextBrain;

package/dist/domain.operations/context/genContextBrain.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.genContextBrain = void 0;
+const helpful_errors_1 = require("helpful-errors");
+const findBrainAtomByRef_1 = require("./findBrainAtomByRef");
+const findBrainReplByRef_1 = require("./findBrainReplByRef");
+/**
+ * .what = factory to create a brain context from plugin-provided atoms and repls
+ * .why =
+ *   - provides a clean entry point for context creation
+ *   - validates no duplicate { repo, slug } identifiers
+ *   - composes the context with lookup and delegation logic
+ */
+const genContextBrain = (input) => {
+    // default to empty arrays
+    const atoms = input.atoms ?? [];
+    const repls = input.repls ?? [];
+    // validate no duplicate atoms
+    const atomKeys = atoms.map((a) => `${a.repo}:${a.slug}`);
+    const duplicateAtom = atomKeys.find((k, i) => atomKeys.indexOf(k) !== i);
+    if (duplicateAtom)
+        throw new helpful_errors_1.BadRequestError('duplicate atom identifier', { duplicateAtom });
+    // validate no duplicate repls
+    const replKeys = repls.map((r) => `${r.repo}:${r.slug}`);
+    const duplicateRepl = replKeys.find((k, i) => replKeys.indexOf(k) !== i);
+    if (duplicateRepl)
+        throw new helpful_errors_1.BadRequestError('duplicate repl identifier', { duplicateRepl });
+    // return context with lookup and delegation
+    return {
+        brain: {
+            atom: {
+                ask: async (askInput) => {
+                    const atom = (0, findBrainAtomByRef_1.findBrainAtomByRef)({ atoms, ref: askInput.brain });
+                    return atom.ask(askInput, {});
+                },
+            },
+            repl: {
+                ask: async (askInput) => {
+                    const repl = (0, findBrainReplByRef_1.findBrainReplByRef)({ repls, ref: askInput.brain });
+                    return repl.ask(askInput, {});
+                },
+                act: async (actInput) => {
+                    const repl = (0, findBrainReplByRef_1.findBrainReplByRef)({ repls, ref: actInput.brain });
+                    return repl.act(actInput, {});
+                },
+            },
+        },
+    };
+};
+exports.genContextBrain = genContextBrain;
+//# sourceMappingURL=genContextBrain.js.map

package/dist/domain.operations/context/genContextBrain.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"genContextBrain.js","sourceRoot":"","sources":["../../../src/domain.operations/context/genContextBrain.ts"],"names":[],"mappings":";;;AAAA,mDAAiD;AAMjD,6DAA0D;AAC1D,6DAA0D;AAE1D;;;;;;GAMG;AACI,MAAM,eAAe,GAAG,CAAC,KAG/B,EAAgB,EAAE;IACjB,0BAA0B;IAC1B,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,IAAI,EAAE,CAAC;IAChC,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,IAAI,EAAE,CAAC;IAEhC,8BAA8B;IAC9B,MAAM,QAAQ,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;IACzD,MAAM,aAAa,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC;IACzE,IAAI,aAAa;QACf,MAAM,IAAI,gCAAe,CAAC,2BAA2B,EAAE,EAAE,aAAa,EAAE,CAAC,CAAC;IAE5E,8BAA8B;IAC9B,MAAM,QAAQ,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;IACzD,MAAM,aAAa,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC;IACzE,IAAI,aAAa;QACf,MAAM,IAAI,gCAAe,CAAC,2BAA2B,EAAE,EAAE,aAAa,EAAE,CAAC,CAAC;IAE5E,4CAA4C;IAC5C,OAAO;QACL,KAAK,EAAE;YACL,IAAI,EAAE;gBACJ,GAAG,EAAE,KAAK,EAAE,QAAQ,EAAE,EAAE;oBACtB,MAAM,IAAI,GAAG,IAAA,uCAAkB,EAAC,EAAE,KAAK,EAAE,GAAG,EAAE,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC;oBAChE,OAAO,IAAI,CAAC,GAAG,CAAC,QAAQ,EAAE,EAAE,CAAQ,CAAC;gBACvC,CAAC;aACF;YACD,IAAI,EAAE;gBACJ,GAAG,EAAE,KAAK,EAAE,QAAQ,EAAE,EAAE;oBACtB,MAAM,IAAI,GAAG,IAAA,uCAAkB,EAAC,EAAE,KAAK,EAAE,GAAG,EAAE,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC;oBAChE,OAAO,IAAI,CAAC,GAAG,CAAC,QAAQ,EAAE,EAAE,CAAQ,CAAC;gBACvC,CAAC;gBACD,GAAG,EAAE,KAAK,EAAE,QAAQ,EAAE,EAAE;oBACtB,MAAM,IAAI,GAAG,IAAA,uCAAkB,EAAC,EAAE,KAAK,EAAE,GAAG,EAAE,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC;oBAChE,OAAO,IAAI,CAAC,GAAG,CAAC,QAAQ,EAAE,EAAE,CAAQ,CAAC;gBACvC,CAAC;aACF;SACF;KACF,CAAC;AACJ,CAAC,CAAC;AAzCW,QAAA,eAAe,mBAyC1B"}

package/dist/domain.operations/invoke/executeSkill.d.ts

@@ -2,8 +2,10 @@ import type { RoleSkillExecutable } from '../../domain.objects/RoleSkillExecutab
 /**
  * .what = executes a skill script with passthrough args
  * .why = runs the discovered skill with full arg passthrough
+ *
+ * .note = captures stdout and parses JSON output when available
  */
 export declare const executeSkill: (input: {
     skill: RoleSkillExecutable;
     args: string[];
-}) => void;
+}) => unknown;

package/dist/domain.operations/invoke/executeSkill.js

@@ -5,6 +5,8 @@ const node_child_process_1 = require("node:child_process");
 /**
  * .what = executes a skill script with passthrough args
  * .why = runs the discovered skill with full arg passthrough
+ *
+ * .note = captures stdout and parses JSON output when available
  */
 const executeSkill = (input) => {
     // build command with args
@@ -16,12 +18,23 @@ const executeSkill = (input) => {
         return arg;
     })
         .join(' ');
-    // execute with inherited stdio
-    (0, node_child_process_1.execSync)(command, {
+    // execute and capture stdout
+    const stdout = (0, node_child_process_1.execSync)(command, {
         cwd: process.cwd(),
-        stdio: 'inherit',
         shell: '/bin/bash',
+        encoding: 'utf-8',
     });
+    // parse JSON output if present
+    const trimmed = stdout.trim();
+    if (!trimmed)
+        return undefined;
+    try {
+        return JSON.parse(trimmed);
+    }
+    catch {
+        // return raw string if not valid JSON
+        return trimmed;
+    }
 };
 exports.executeSkill = executeSkill;
 //# sourceMappingURL=executeSkill.js.map

package/dist/domain.operations/invoke/executeSkill.js.map

@@ -1 +1 @@
-{"version":3,"file":"executeSkill.js","sourceRoot":"","sources":["../../../src/domain.operations/invoke/executeSkill.ts"],"names":[],"mappings":";;;AAEA,2DAA8C;AAE9C;;;GAGG;AACI,MAAM,YAAY,GAAG,CAAC,KAG5B,EAAQ,EAAE;IACT,0BAA0B;IAC1B,MAAM,OAAO,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,EAAE,GAAG,KAAK,CAAC,IAAI,CAAC;SAC9C,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE;QACX,yBAAyB;QACzB,IAAI,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC;YAAE,OAAO,IAAI,GAAG,GAAG,CAAC;QACzC,OAAO,GAAG,CAAC;IACb,CAAC,CAAC;SACD,IAAI,CAAC,GAAG,CAAC,CAAC;IAEb,+BAA+B;IAC/B,IAAA,6BAAQ,EAAC,OAAO,EAAE;QAChB,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE;QAClB,KAAK,EAAE,SAAS;QAChB,KAAK,EAAE,WAAW;KACnB,CAAC,CAAC;AACL,CAAC,CAAC;AAnBW,QAAA,YAAY,gBAmBvB"}
+{"version":3,"file":"executeSkill.js","sourceRoot":"","sources":["../../../src/domain.operations/invoke/executeSkill.ts"],"names":[],"mappings":";;;AAEA,2DAA8C;AAE9C;;;;;GAKG;AACI,MAAM,YAAY,GAAG,CAAC,KAG5B,EAAW,EAAE;IACZ,0BAA0B;IAC1B,MAAM,OAAO,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,EAAE,GAAG,KAAK,CAAC,IAAI,CAAC;SAC9C,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE;QACX,yBAAyB;QACzB,IAAI,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC;YAAE,OAAO,IAAI,GAAG,GAAG,CAAC;QACzC,OAAO,GAAG,CAAC;IACb,CAAC,CAAC;SACD,IAAI,CAAC,GAAG,CAAC,CAAC;IAEb,6BAA6B;IAC7B,MAAM,MAAM,GAAG,IAAA,6BAAQ,EAAC,OAAO,EAAE;QAC/B,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE;QAClB,KAAK,EAAE,WAAW;QAClB,QAAQ,EAAE,OAAO;KAClB,CAAC,CAAC;IAEH,+BAA+B;IAC/B,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,EAAE,CAAC;IAC9B,IAAI,CAAC,OAAO;QAAE,OAAO,SAAS,CAAC;IAE/B,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IAC7B,CAAC;IAAC,MAAM,CAAC;QACP,sCAAsC;QACtC,OAAO,OAAO,CAAC;IACjB,CAAC;AACH,CAAC,CAAC;AA9BW,QAAA,YAAY,gBA8BvB"}

package/dist/domain.operations/invoke/getBrainReplsByOpts.d.ts

@@ -0,0 +1,14 @@
+import type { BrainRepl } from '../../domain.objects';
+import type { InvokeOpts } from '../../domain.objects/InvokeOpts';
+/**
+ * .what = get brain repls from the invocation options declared
+ * .why = enables CLI commands to resolve brains from config
+ * .how =
+ *   - lookup the config based on the options
+ *   - grab the brain repls from the config
+ */
+export declare const getBrainReplsByOpts: (input: {
+    opts: InvokeOpts<{
+        config: string;
+    }>;
+}) => Promise<BrainRepl[]>;

package/dist/domain.operations/invoke/getBrainReplsByOpts.js

@@ -0,0 +1,43 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getBrainReplsByOpts = void 0;
+/**
+ * .what = get brain repls from the invocation options declared
+ * .why = enables CLI commands to resolve brains from config
+ * .how =
+ *   - lookup the config based on the options
+ *   - grab the brain repls from the config
+ */
+const getBrainReplsByOpts = async (input) => {
+    // import the config
+    const config = await Promise.resolve(`${input.opts.config}`).then(s => __importStar(require(s)));
+    // grab the brain repls if available
+    if (!config.getBrainRepls)
+        return [];
+    return await config.getBrainRepls();
+};
+exports.getBrainReplsByOpts = getBrainReplsByOpts;
+//# sourceMappingURL=getBrainReplsByOpts.js.map

package/dist/domain.operations/invoke/getBrainReplsByOpts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"getBrainReplsByOpts.js","sourceRoot":"","sources":["../../../src/domain.operations/invoke/getBrainReplsByOpts.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;AAGA;;;;;;GAMG;AACI,MAAM,mBAAmB,GAAG,KAAK,EAAE,KAEzC,EAAwB,EAAE;IACzB,oBAAoB;IACpB,MAAM,MAAM,GAAmD,yBAC7D,KAAK,CAAC,IAAI,CAAC,MAAM,uCAClB,CAAC;IAEF,oCAAoC;IACpC,IAAI,CAAC,MAAM,CAAC,aAAa;QAAE,OAAO,EAAE,CAAC;IAErC,OAAO,MAAM,MAAM,CAAC,aAAa,EAAE,CAAC;AACtC,CAAC,CAAC;AAZW,QAAA,mBAAmB,uBAY9B"}

package/dist/domain.operations/schema/castZodToJsonSchema.d.ts

@@ -0,0 +1,14 @@
+import type { z } from 'zod';
+/**
+ * .what = convert a zod schema to JSON schema for native SDK enforcement
+ * .why = enables native structured output support in SDKs, reducing
+ *   token waste on validation retries
+ *
+ * .note = different SDKs require different conversion options:
+ *   - claude-agent-sdk: { $refStrategy: 'root' }
+ *   - codex-sdk: { target: 'openAi' }
+ */
+export declare const castZodToJsonSchema: (input: {
+    schema: z.ZodSchema;
+    target: 'claude' | 'openai';
+}) => object;

package/dist/domain.operations/schema/castZodToJsonSchema.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.castZodToJsonSchema = void 0;
+const zod_to_json_schema_1 = require("zod-to-json-schema");
+/**
+ * .what = convert a zod schema to JSON schema for native SDK enforcement
+ * .why = enables native structured output support in SDKs, reducing
+ *   token waste on validation retries
+ *
+ * .note = different SDKs require different conversion options:
+ *   - claude-agent-sdk: { $refStrategy: 'root' }
+ *   - codex-sdk: { target: 'openAi' }
+ */
+const castZodToJsonSchema = (input) => {
+    // convert based on target SDK
+    if (input.target === 'claude') {
+        return (0, zod_to_json_schema_1.zodToJsonSchema)(input.schema, { $refStrategy: 'root' });
+    }
+    // openai target
+    return (0, zod_to_json_schema_1.zodToJsonSchema)(input.schema, { target: 'openAi' });
+};
+exports.castZodToJsonSchema = castZodToJsonSchema;
+//# sourceMappingURL=castZodToJsonSchema.js.map

package/dist/domain.operations/schema/castZodToJsonSchema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"castZodToJsonSchema.js","sourceRoot":"","sources":["../../../src/domain.operations/schema/castZodToJsonSchema.ts"],"names":[],"mappings":";;;AACA,2DAAqD;AAErD;;;;;;;;GAQG;AACI,MAAM,mBAAmB,GAAG,CAAC,KAGnC,EAAU,EAAE;IACX,8BAA8B;IAC9B,IAAI,KAAK,CAAC,MAAM,KAAK,QAAQ,EAAE,CAAC;QAC9B,OAAO,IAAA,oCAAe,EAAC,KAAK,CAAC,MAAM,EAAE,EAAE,YAAY,EAAE,MAAM,EAAE,CAAC,CAAC;IACjE,CAAC;IAED,gBAAgB;IAChB,OAAO,IAAA,oCAAe,EAAC,KAAK,CAAC,MAAM,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,CAAC;AAC7D,CAAC,CAAC;AAXW,QAAA,mBAAmB,uBAW9B"}

package/package.json

@@ -2,7 +2,7 @@
   "name": "rhachet",
   "author": "ehmpathy",
   "description": "A framework for reliable, thorough thought. Weave threads of thought via stitches.",
-  "version": "1.17.0",
+  "version": "1.19.0",
   "repository": "ehmpathy/rhachet",
   "homepage": "https://github.com/ehmpathy/rhachet",
   "keywords": [
@@ -54,6 +54,8 @@
     "prepare:rhachet": "rhachet init && rhachet roles link --repo ehmpathy --role mechanic && rhachet roles link --repo bhuild --role behaver && rhachet roles link --repo bhrain --role reviewer && rhachet roles init --role mechanic && rhachet roles init --role behaver"
   },
   "dependencies": {
+    "@anthropic-ai/claude-agent-sdk": "0.1.76",
+    "@anthropic-ai/sdk": "0.71.2",
     "@ehmpathy/uni-time": "1.9.0",
     "as-procedure": "1.1.6",
     "bottleneck": "2.19.5",
@@ -63,12 +65,15 @@
     "fast-glob": "3.3.3",
     "flattie": "1.1.1",
     "helpful-errors": "1.5.3",
+    "@openai/codex-sdk": "0.77.0",
     "openai": "5.8.2",
     "rhachet-artifact": "1.0.1",
     "rhachet-artifact-git": "1.1.3",
     "serde-fns": "1.3.1",
     "type-fns": "1.21.0",
-    "uuid-fns": "1.0.1"
+    "uuid-fns": "1.0.1",
+    "zod": "3.25.76",
+    "zod-to-json-schema": "3.25.1"
   },
   "devDependencies": {
     "@biomejs/biome": "2.3.8",

package/readme.md

@@ -3,31 +3,73 @@
 ![test](https://github.com/ehmpathy/rhachet/workflows/test/badge.svg)
 ![publish](https://github.com/ehmpathy/rhachet/workflows/publish/badge.svg)
 
-Build reusable roles with rhachet: a framework for reliable, composable, and iteratively improvable thought.
+a framework for reliable, composable, and iteratively improvable thought.
 
-> Weave threads 🧵 of thought, stitched 🪡  with a rhachet ⚙️
+> weave threads 🧵 of thought, stitched 🪡 with a rhachet ⚙️
 
-# vision
+# purpose
 
-Build or use digital actors, who work even from your laptop, and work for anyone you choose.
+rhachet makes it simple to leverage thought routes - safely, easily, and effectively.
 
-Distill your skills and roles iteratively, with rhachet. Use them, compose them, share them, open source them. The choice is yours.
+- 🪨 **solid** routes for deterministic automation
+- 🔩 **rigid** routes for augmented workflows
+- 🌊 **fluid** routes for open-ended exploration
 
-- With open source top to bottom, we can raise the floor and prosper collectively.
-- With observable routes of thought, we can not only debug, but align.
-- With composable thought routes, we can build incremental complexity and automate test coverage just like any code.
+with rhachet, you can:
+- declare thought routes, reusably and maintainably
+- apply thought routes, observably and reliably
+- compose and accumulate reusable thought skill
+- assure slipless progress towards goals, like a ratchet (🎼 click, click, click)
+- enable iterative improvement of skills, like a ratchet (🎼 click, click, click)
 
-Here's to a solarpunk future of abundance 🌞🌴
+# concepts
 
-# purpose
+## thought routes
+
+thought routes describe the determinism profile of an execution path.
+
+| route       | what                                             | when to use                          |
+| ----------- | ------------------------------------------------ | ------------------------------------ |
+| 🪨 **solid** | deterministic throughout                         | scripted automation, data transforms |
+| 🔩 **rigid** | deterministic harness + probabilistic operations | augmented workflows, controlled ai   |
+| 🌊 **fluid** | probabilistic throughout                         | exploration, open-ended problems     |
+
+the key distinction:
+- 🔩 **rigid**: you know when thought is needed, harness controls
+- 🌊 **fluid**: you don't know when or what thought is needed, brain decides
+
+## brains
+
+brains are probabilistic imagination mechanisms that provide creative thought capabilities:
+
+| type | what | characteristics |
+| ---- | ---- | --------------- |
+| **brain.atom** | single inference | stateless, one-shot |
+| **brain.repl** | read-eval-print-loop | stateful, multi-turn, tool use |
+
+brain.atom is for single-turn operations. brain.repl is for multi-turn operations.
+
+## actors, roles, skills, briefs
+
+rhachet organizes thought operators into a composable hierarchy:
+
+```
+actor = brain + role
+role = skills + briefs
+```
 
-1. declare thought routes, reusably and maintainably
-2. apply thought routes, observably and reliably
-3. compose and accumulate reusable thought skill
-4. assure slipless progress towards goals, like a ratchet (🎼 click, click, click)
-5. enable iterative improvement of skills, like a ratchet (🎼 click, click, click)
-6. assure guarded budgets of money and time, with route plans, expense approvals, and circuit breakers
-7. observe thought routes and weaves intuitively
+| concept   | what                               | example                                 |
+| --------- | ---------------------------------- | --------------------------------------- |
+| **actor** | a brain assuming a role            | mechanic actor (claude + mechanic role) |
+| **role**  | a bundle of skills + briefs        | mechanic, reviewer, architect           |
+| **skill** | an executable capability           | review, deliver, init                   |
+| **brief** | context and knowledge for the role | coding standards, domain patterns       |
+
+roles are portable - the same role can be assumed by different brains.
+
+skills are composable - they can invoke other skills, nest thought routes, and build complexity incrementally.
+
+briefs are cumulative - they encode institutional knowledge that improves over time.
 
 # install
 
@@ -37,43 +79,142 @@ npm install rhachet
 
 # use
 
+## cli
+
+rhachet provides cli commands for each thought route:
 
-## use a prebuilt roles registry
+| command           | route   | what it does                               |
+| ----------------- | ------- | ------------------------------------------ |
+| `npx rhachet run` | 🪨 solid | execute a shell skill, no brain            |
+| `npx rhachet act` | 🔩 rigid | execute a skill with deterministic harness |
+| `npx rhachet ask` | 🌊 fluid | converse with an actor, brain decides path |
 
-### setup your config file
+### setup
 
-looks for `@gitroot/rhachet.use.ts` by default
+rhachet looks for `@gitroot/rhachet.use.ts`:
 
 ```ts
-// @/rhachet.use.ts
+// rhachet.use.ts
 import { getRoleRegistry as getBhrainRegistry } from 'rhachet-roles-bhrain';
 import { getRoleRegistry as getEhmpathyRegistry } from 'rhachet-roles-ehmpathy';
 
 export const getRoleRegistries = () => [
   getBhrainRegistry(),
   getEhmpathyRegistry(),
-  // whichever other registries you'd like
-]
+];
 ```
 
-### perform a skill
+### 🪨 solid: run
 
 ```sh
-npx rhachet act \
-  --repo bhrain --role skeptic --skill review \
-  --ask "are birds real? or are they just government drones 🤔"
+npx rhachet run --skill gh.workflow.logs --workflow test
 ```
 
+deterministic execution, no brain involved.
+
+### 🔩 rigid: act
+
 ```sh
 npx rhachet act \
-  --repo ehmpathy --role mechanic --skill review \
-  --input "https://github.com/ehmpathy/simple-in-memory-cache/pull/9" \
-  --ask "review this pr"
+  --role mechanic --skill review \
+  --input "https://github.com/org/repo/pull/9"
+
+npx rhachet act \
+  --role mechanic --skill review \
+  --input "https://github.com/org/repo/pull/9" \
+  --brain openai/codex
 ```
 
+deterministic harness controls flow, brain operations are wrapped and validated.
+
+### 🌊 fluid: ask
+
 ```sh
-npx rhachet act \
-  --repo ehmpathy --role mechanic --skill deliver \
-  --input "https://github.com/ehmpathy/domain-objects/issues/7" \
-  --ask "push a pr to solve the issue"
+npx rhachet ask \
+  --role skeptic \
+  --ask "are birds real?"
+```
+
+brain decides the path, exploration is the goal.
+
+## sdk
+
+rhachet provides a type-safe sdk for programmatic actor usage.
+
+| method         | route   | what it does                               |
+| -------------- | ------- | ------------------------------------------ |
+| `actor.run()`  | 🪨 solid | execute a shell skill, no brain            |
+| `actor.act()`  | 🔩 rigid | execute a skill with deterministic harness |
+| `actor.ask()`  | 🌊 fluid | converse with an actor, brain decides path |
+
+### setup
+
+generate an actor from a role with an allowlist of brains:
+
+```ts
+import { genActor } from 'rhachet';
+import { genBrainRepl } from 'rhachet-brains-openai';
+import { mechanicRole } from './roles/mechanic';
+
+export const mechanic = genActor({
+  role: mechanicRole,
+  brains: [
+    genBrainRepl({ slug: 'openai/codex' }),       // default (first in list)
+    genBrainRepl({ slug: 'openai/codex/mini' }),  // fast + cheap alternative
+  ],
+});
 ```
+
+the `brains` allowlist:
+- defines which brains this actor supports
+- first brain is the default (used when no explicit brain is provided)
+- ensures only allowlisted brains can be used
+
+### 🪨 solid: run
+
+```ts
+await mechanic.run({
+  skill: { 'gh.workflow.logs': { workflow: 'test' } },
+});
+```
+
+deterministic execution, no brain involved.
+
+### 🔩 rigid: act
+
+```ts
+// uses default brain (first in allowlist)
+await mechanic.act({
+  skill: { review: { input: 'https://github.com/org/repo/pull/9' } },
+});
+
+// uses explicit brain (must be in allowlist)
+await mechanic.act({
+  brain: { repo: 'openai', slug: 'codex/mini' },
+  skill: { review: { input: 'https://github.com/org/repo/pull/9' } },
+});
+```
+
+deterministic harness controls flow, brain operations are wrapped and validated.
+
+### 🌊 fluid: ask
+
+```ts
+await mechanic.ask({
+  prompt: 'are birds real?',
+});
+```
+
+brain decides the path, exploration is the goal.
+
+# vision
+
+build or use digital actors, who work even from your laptop, and work for anyone you choose.
+
+distill your skills and roles iteratively, with rhachet. use them, compose them, share them, open source them. the choice is yours.
+
+- with open source top to bottom, we can raise the floor and prosper collectively.
+- with observable routes of thought, we can not only debug, but align.
+- with composable thought routes, we can build incremental complexity and automate test coverage just like any code.
+
+here's to a solarpunk future of abundance 🌞🌴