rhachet 1.18.0 → 1.19.0

package/dist/domain.operations/actor/genActor.d.ts

@@ -0,0 +1,18 @@
+import { Actor } from '../../domain.objects/Actor';
+import type { BrainRepl } from '../../domain.objects/BrainRepl';
+import type { Role } from '../../domain.objects/Role';
+/**
+ * .what = creates an actor from a role and brain allowlist
+ * .why = composes role (skills + briefs) with brains for type-safe invocation
+ *
+ * .note =
+ *   - first brain in allowlist is the default
+ *   - .act() uses default brain when none specified
+ *   - .act() validates brain against allowlist when specified
+ *   - .run() executes solid skills without brain
+ *   - .ask() starts fluid conversation with default brain
+ */
+export declare const genActor: <TRole extends Role<import("../../domain.objects/Role").RoleSkillRegistry, import("../../domain.objects/Role").RoleSkillRegistry>>(input: {
+    role: TRole;
+    brains: BrainRepl[];
+}) => Actor<TRole>;

package/dist/domain.operations/actor/genActor.js

@@ -0,0 +1,98 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.genActor = void 0;
+const helpful_errors_1 = require("helpful-errors");
+const Actor_1 = require("../../domain.objects/Actor");
+const actorAct_1 = require("./actorAct");
+const actorAsk_1 = require("./actorAsk");
+const actorRun_1 = require("./actorRun");
+const findActorBrainInAllowlist_1 = require("./findActorBrainInAllowlist");
+const findActorRoleSkillBySlug_1 = require("./findActorRoleSkillBySlug");
+/**
+ * .what = creates an actor from a role and brain allowlist
+ * .why = composes role (skills + briefs) with brains for type-safe invocation
+ *
+ * .note =
+ *   - first brain in allowlist is the default
+ *   - .act() uses default brain when none specified
+ *   - .act() validates brain against allowlist when specified
+ *   - .run() executes solid skills without brain
+ *   - .ask() starts fluid conversation with default brain
+ */
+const genActor = (input) => {
+    // validate that at least one brain is provided
+    if (input.brains.length === 0)
+        throw new helpful_errors_1.BadRequestError('genActor requires at least one brain in allowlist', { roleSlug: input.role.slug });
+    // extract default brain (first in list)
+    const defaultBrain = input.brains[0];
+    // create bound .act() method with strong types
+    const act = async (actInput) => {
+        // resolve brain: use provided or default to first
+        const brainResolved = actInput.brain
+            ? (0, findActorBrainInAllowlist_1.findActorBrainInAllowlist)({
+                brain: actInput.brain,
+                allowlist: input.brains,
+            })
+            : defaultBrain;
+        // extract skill slug and args from skill object
+        const entries = Object.entries(actInput.skill);
+        if (entries.length !== 1)
+            throw new helpful_errors_1.BadRequestError('actor.act expects exactly one skill entry', {
+                entriesCount: entries.length,
+            });
+        const [skillSlug, skillArgs] = entries[0];
+        // resolve skill from role
+        const skillResolved = (0, findActorRoleSkillBySlug_1.findActorRoleSkillBySlug)({
+            slug: skillSlug,
+            role: input.role,
+            route: 'rigid',
+        });
+        // delegate to actorAct with pre-resolved skill
+        return (0, actorAct_1.actorAct)({
+            role: input.role,
+            brain: brainResolved,
+            skill: skillResolved,
+            args: skillArgs,
+        });
+    };
+    // create bound .run() method with strong types
+    const run = async (runInput) => {
+        // extract skill slug and args from skill object
+        const entries = Object.entries(runInput.skill);
+        if (entries.length !== 1)
+            throw new helpful_errors_1.BadRequestError('actor.run expects exactly one skill entry', {
+                entriesCount: entries.length,
+            });
+        const [skillSlug, skillArgs] = entries[0];
+        // resolve skill from role
+        const skillResolved = (0, findActorRoleSkillBySlug_1.findActorRoleSkillBySlug)({
+            slug: skillSlug,
+            role: input.role,
+            route: 'solid',
+        });
+        // delegate to actorRun with pre-resolved skill
+        return (0, actorRun_1.actorRun)({
+            skill: skillResolved,
+            args: skillArgs,
+        });
+    };
+    // create bound .ask() method
+    const ask = async (askInput) => {
+        // delegate to actorAsk with default brain
+        return (0, actorAsk_1.actorAsk)({
+            role: input.role,
+            brain: defaultBrain,
+            prompt: askInput.prompt,
+        });
+    };
+    // return actor with bound methods via Actor.typed() for strong type preservation
+    return Actor_1.Actor.typed({
+        role: input.role,
+        brains: input.brains,
+        act,
+        run,
+        ask,
+    });
+};
+exports.genActor = genActor;
+//# sourceMappingURL=genActor.js.map

package/dist/domain.operations/actor/genActor.js.map

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

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/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.18.0",
+  "version": "1.19.0",
   "repository": "ehmpathy/rhachet",
   "homepage": "https://github.com/ehmpathy/rhachet",
   "keywords": [

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 🌞🌴