rhachet-roles-bhrain 0.3.0 → 0.5.1

package/dist/domain.operations/reflect/validateTargetDirectory.js

@@ -0,0 +1,59 @@
+"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.validateTargetDirectory = void 0;
+const fs = __importStar(require("fs/promises"));
+const helpful_errors_1 = require("helpful-errors");
+/**
+ * .what = validates target directory exists or creates with --force
+ * .why = fail fast on invalid target before expensive operations
+ */
+const validateTargetDirectory = async (input) => {
+    // check if directory exists
+    try {
+        const stat = await fs.stat(input.target);
+        if (!stat.isDirectory())
+            throw new helpful_errors_1.BadRequestError('target path exists but is not a directory', {
+                target: input.target,
+            });
+        return { created: false };
+    }
+    catch (error) {
+        // if not a BadRequestError, directory doesn't exist
+        if (error instanceof helpful_errors_1.BadRequestError)
+            throw error;
+        // directory doesn't exist - check if we should create it
+        if (!input.force)
+            throw new helpful_errors_1.BadRequestError('target directory does not exist. use --force to create it.', {
+                target: input.target,
+                hint: 'add --force flag to create the target directory',
+            });
+        // create directory with --force
+        await fs.mkdir(input.target, { recursive: true });
+        return { created: true };
+    }
+};
+exports.validateTargetDirectory = validateTargetDirectory;
+//# sourceMappingURL=validateTargetDirectory.js.map

package/dist/domain.operations/reflect/validateTargetDirectory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validateTargetDirectory.js","sourceRoot":"","sources":["../../../src/domain.operations/reflect/validateTargetDirectory.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;AAAA,gDAAkC;AAClC,mDAAiD;AAEjD;;;GAGG;AACI,MAAM,uBAAuB,GAAG,KAAK,EAAE,KAG7C,EAEE,EAAE;IACH,4BAA4B;IAC5B,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,MAAM,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;QACzC,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE;YACrB,MAAM,IAAI,gCAAe,CAAC,2CAA2C,EAAE;gBACrE,MAAM,EAAE,KAAK,CAAC,MAAM;aACrB,CAAC,CAAC;QACL,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;IAC5B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,oDAAoD;QACpD,IAAI,KAAK,YAAY,gCAAe;YAAE,MAAM,KAAK,CAAC;QAElD,yDAAyD;QACzD,IAAI,CAAC,KAAK,CAAC,KAAK;YACd,MAAM,IAAI,gCAAe,CACvB,4DAA4D,EAC5D;gBACE,MAAM,EAAE,KAAK,CAAC,MAAM;gBACpB,IAAI,EAAE,iDAAiD;aACxD,CACF,CAAC;QAEJ,gCAAgC;QAChC,MAAM,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,MAAM,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAClD,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;IAC3B,CAAC;AACH,CAAC,CAAC;AAhCW,QAAA,uBAAuB,2BAgClC"}

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,iDAA+B"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,oDAAkC"}

package/dist/roles/architect/getArchitectRole.d.ts

@@ -0,0 +1,6 @@
+import { Role } from 'rhachet';
+/**
+ * .what = role definition for the architect
+ * .why = documents and compares architectures of replic brains (LLMs behind REPLs)
+ */
+export declare const ROLE_ARCHITECT: Role;

package/dist/roles/architect/getArchitectRole.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ROLE_ARCHITECT = void 0;
+const rhachet_1 = require("rhachet");
+/**
+ * .what = role definition for the architect
+ * .why = documents and compares architectures of replic brains (LLMs behind REPLs)
+ */
+exports.ROLE_ARCHITECT = rhachet_1.Role.build({
+    slug: 'architect',
+    name: 'Architect',
+    purpose: 'brain architecture patterns',
+    readme: `
+## 🏗️ Architect
+
+- **scale**: conceptual, architectural
+- **focus**: brain architecture patterns
+- **maximizes**: understanding of how artificial brains are constructed
+
+used to document and compare architectures of replic brains (LLMs behind REPLs).
+  `.trim(),
+    traits: [],
+    skills: {
+        dirs: [],
+        refs: [],
+    },
+    briefs: {
+        dirs: [{ uri: __dirname + '/briefs' }],
+    },
+});
+//# sourceMappingURL=getArchitectRole.js.map

package/dist/roles/architect/getArchitectRole.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"getArchitectRole.js","sourceRoot":"","sources":["../../../src/roles/architect/getArchitectRole.ts"],"names":[],"mappings":";;;AAAA,qCAA+B;AAE/B;;;GAGG;AACU,QAAA,cAAc,GAAS,cAAI,CAAC,KAAK,CAAC;IAC7C,IAAI,EAAE,WAAW;IACjB,IAAI,EAAE,WAAW;IACjB,OAAO,EAAE,6BAA6B;IACtC,MAAM,EAAE;;;;;;;;GAQP,CAAC,IAAI,EAAE;IACR,MAAM,EAAE,EAAE;IACV,MAAM,EAAE;QACN,IAAI,EAAE,EAAE;QACR,IAAI,EAAE,EAAE;KACT;IACD,MAAM,EAAE;QACN,IAAI,EAAE,CAAC,EAAE,GAAG,EAAE,SAAS,GAAG,SAAS,EAAE,CAAC;KACvC;CACF,CAAC,CAAC"}

package/dist/roles/brain/getBrainRole.d.ts

@@ -0,0 +1,6 @@
+import { Role } from 'rhachet';
+/**
+ * .what = role definition for the brain
+ * .why = exposes agentic capabilities as rhachet skills for tool-using llm workflows
+ */
+export declare const ROLE_BRAIN: Role;

package/dist/roles/brain/getBrainRole.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ROLE_BRAIN = void 0;
+const rhachet_1 = require("rhachet");
+const skillAct_1 = require("../../roles/brain/skills/act/skillAct");
+/**
+ * .what = role definition for the brain
+ * .why = exposes agentic capabilities as rhachet skills for tool-using llm workflows
+ */
+exports.ROLE_BRAIN = rhachet_1.Role.build({
+    slug: 'brain',
+    name: 'Brain',
+    purpose: 'agentic entooled brain',
+    readme: `
+## 🧠 Brain
+
+a brain.repl available for agentic tooluse
+  `.trim(),
+    traits: [],
+    skills: {
+        dirs: [],
+        refs: [skillAct_1.SKILL_ACT],
+    },
+    briefs: {
+        dirs: [],
+    },
+});
+//# sourceMappingURL=getBrainRole.js.map

package/dist/roles/brain/getBrainRole.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"getBrainRole.js","sourceRoot":"","sources":["../../../src/roles/brain/getBrainRole.ts"],"names":[],"mappings":";;;AAAA,qCAA+B;AAE/B,mEAAiE;AAEjE;;;GAGG;AACU,QAAA,UAAU,GAAS,cAAI,CAAC,KAAK,CAAC;IACzC,IAAI,EAAE,OAAO;IACb,IAAI,EAAE,OAAO;IACb,OAAO,EAAE,wBAAwB;IACjC,MAAM,EAAE;;;;GAIP,CAAC,IAAI,EAAE;IACR,MAAM,EAAE,EAAE;IACV,MAAM,EAAE;QACN,IAAI,EAAE,EAAE;QACR,IAAI,EAAE,CAAC,oBAAS,CAAC;KAClB;IACD,MAAM,EAAE;QACN,IAAI,EAAE,EAAE;KACT;CACF,CAAC,CAAC"}

package/dist/roles/brain/skills/act/skillAct.d.ts

@@ -0,0 +1,5 @@
+/**
+ * .what = skill definition for agentic task completion
+ * .why = enables rhachet roles to leverage brain capabilities for autonomous task execution
+ */
+export declare const SKILL_ACT: import("rhachet").RoleSkill<import("./stepAct").StitcherAct>;

package/dist/roles/brain/skills/act/skillAct.js

@@ -0,0 +1,147 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SKILL_ACT = void 0;
+const rhachet_1 = require("rhachet");
+const rhachet_artifact_git_1 = require("rhachet-artifact-git");
+const genContextLogTrail_1 = require("../../../../.test/genContextLogTrail");
+const BrainArch1Actor_1 = require("../../../../domain.objects/BrainArch1/BrainArch1Actor");
+const anthropic_1 = require("../../../../domain.operations/brain.replic.arch1/plugins/atoms/anthropic");
+const openai_1 = require("../../../../domain.operations/brain.replic.arch1/plugins/atoms/openai");
+const qwen_1 = require("../../../../domain.operations/brain.replic.arch1/plugins/atoms/qwen");
+const readOnly_1 = require("../../../../domain.operations/brain.replic.arch1/plugins/permissionGuards/readOnly");
+const files_1 = require("../../../../domain.operations/brain.replic.arch1/plugins/toolboxes/files");
+const stepAct_1 = require("./stepAct");
+/**
+ * .what = skill definition for agentic task completion
+ * .why = enables rhachet roles to leverage brain capabilities for autonomous task execution
+ */
+exports.SKILL_ACT = (0, rhachet_1.genRoleSkill)({
+    slug: 'act',
+    route: stepAct_1.stepAct,
+    threads: {
+        lookup: {
+            target: {
+                source: 'process.argv',
+                char: 't',
+                desc: 'the target file to write the result to',
+                type: 'string',
+            },
+            provider: {
+                source: 'process.argv',
+                char: 'p',
+                desc: 'the llm provider to use (anthropic, openai, qwen)',
+                type: '?string',
+            },
+            model: {
+                source: 'process.argv',
+                char: 'm',
+                desc: 'the model to use',
+                type: '?string',
+            },
+            system: {
+                source: 'process.argv',
+                char: 's',
+                desc: 'path to system prompt file',
+                type: '?string',
+            },
+        },
+        assess: (input) => typeof input.target === 'string',
+        instantiate: async (input) => {
+            const obsDir = (0, rhachet_artifact_git_1.getArtifactObsDir)({ uri: input.target });
+            // build brain actor from inputs
+            const provider = (input.provider ?? 'anthropic');
+            const model = input.model ?? 'claude-3-5-sonnet-latest';
+            // create atom based on provider
+            const atom = provider === 'anthropic'
+                ? (0, anthropic_1.genAtomAnthropic)({ model })
+                : provider === 'openai'
+                    ? (0, openai_1.genAtomOpenai)({ model })
+                    : (0, qwen_1.genAtomQwen)({ model });
+            const actor = new BrainArch1Actor_1.BrainArch1Actor({
+                atom,
+                toolboxes: [files_1.toolboxFiles],
+                memory: null,
+                permission: readOnly_1.permissionGuardReadOnly,
+                constraints: {
+                    maxIterations: 100,
+                    maxTokens: 8192,
+                },
+                role: {
+                    systemPrompt: null,
+                },
+            });
+            return {
+                caller: await (0, rhachet_1.enrollThread)({
+                    role: 'caller',
+                    stash: {
+                        ask: input.ask,
+                        art: {
+                            result: (0, rhachet_artifact_git_1.genArtifactGitFile)({ uri: input.target }, { versions: true }),
+                            log: (0, rhachet_artifact_git_1.genArtifactGitFile)({ uri: obsDir + '.log.md' }, { versions: true }),
+                        },
+                    },
+                }),
+                brain: await (0, rhachet_1.enrollThread)({
+                    role: 'brain',
+                    stash: {
+                        actor,
+                        systemPromptPath: input.system ?? null,
+                    },
+                }),
+            };
+        },
+    },
+    context: {
+        lookup: {
+            apiKeyAnthropic: {
+                source: 'process.env',
+                envar: 'ANTHROPIC_API_KEY',
+                desc: 'the anthropic api key',
+                type: '?string',
+            },
+            apiKeyOpenai: {
+                source: 'process.env',
+                envar: 'OPENAI_API_KEY',
+                desc: 'the openai api key',
+                type: '?string',
+            },
+            apiKeyQwen: {
+                source: 'process.env',
+                envar: 'QWEN_API_KEY',
+                desc: 'the qwen api key',
+                type: '?string',
+            },
+            apiKeyTavily: {
+                source: 'process.env',
+                envar: 'TAVILY_API_KEY',
+                desc: 'the tavily api key for web search',
+                type: '?string',
+            },
+        },
+        assess: (input) => true,
+        instantiate: (input) => {
+            return {
+                creds: {
+                    anthropic: { apiKey: input.apiKeyAnthropic ?? '', url: null },
+                    openai: { apiKey: input.apiKeyOpenai ?? '', url: null },
+                    qwen: { apiKey: input.apiKeyQwen ?? '', url: null },
+                    tavily: { apiKey: input.apiKeyTavily ?? '' },
+                },
+                ...(0, genContextLogTrail_1.genContextLogTrail)(),
+                ...(0, rhachet_1.genContextStitchTrail)(),
+            };
+        },
+    },
+    readme: `
+# act
+
+invokes the agentic brain loop to complete a task
+
+## usage
+
+\`\`\`bash
+npx rhachet skills run act -t ./output.md "your task here"
+\`\`\`
+  `.trim(),
+});
+//# sourceMappingURL=skillAct.js.map

package/dist/roles/brain/skills/act/skillAct.js.map

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

package/dist/roles/brain/skills/act/skillAct.ts

@@ -0,0 +1,186 @@
+import { enrollThread, genContextStitchTrail, genRoleSkill } from 'rhachet';
+import { genArtifactGitFile, getArtifactObsDir } from 'rhachet-artifact-git';
+
+import { genContextLogTrail } from '@src/.test/genContextLogTrail';
+import { BrainArch1Actor } from '@src/domain.objects/BrainArch1/BrainArch1Actor';
+import { genAtomAnthropic } from '@src/domain.operations/brain.replic.arch1/plugins/atoms/anthropic';
+import { genAtomOpenai } from '@src/domain.operations/brain.replic.arch1/plugins/atoms/openai';
+import { genAtomQwen } from '@src/domain.operations/brain.replic.arch1/plugins/atoms/qwen';
+import { permissionGuardReadOnly } from '@src/domain.operations/brain.replic.arch1/plugins/permissionGuards/readOnly';
+import { toolboxFiles } from '@src/domain.operations/brain.replic.arch1/plugins/toolboxes/files';
+
+import { stepAct } from './stepAct';
+
+/**
+ * .what = skill definition for agentic task completion
+ * .why = enables rhachet roles to leverage brain capabilities for autonomous task execution
+ */
+export const SKILL_ACT = genRoleSkill({
+  slug: 'act',
+  route: stepAct,
+  threads: {
+    lookup: {
+      target: {
+        source: 'process.argv',
+        char: 't',
+        desc: 'the target file to write the result to',
+        type: 'string',
+      },
+      provider: {
+        source: 'process.argv',
+        char: 'p',
+        desc: 'the llm provider to use (anthropic, openai, qwen)',
+        type: '?string',
+      },
+      model: {
+        source: 'process.argv',
+        char: 'm',
+        desc: 'the model to use',
+        type: '?string',
+      },
+      system: {
+        source: 'process.argv',
+        char: 's',
+        desc: 'path to system prompt file',
+        type: '?string',
+      },
+    },
+    assess: (
+      input,
+    ): input is {
+      target: string;
+      provider: string;
+      model: string;
+      system: string;
+      ask: string;
+    } => typeof input.target === 'string',
+    instantiate: async (input: {
+      target: string;
+      provider: string;
+      model: string;
+      system: string;
+      ask: string;
+    }) => {
+      const obsDir = getArtifactObsDir({ uri: input.target });
+
+      // build brain actor from inputs
+      const provider = (input.provider ?? 'anthropic') as
+        | 'anthropic'
+        | 'openai'
+        | 'qwen';
+      const model = input.model ?? 'claude-3-5-sonnet-latest';
+
+      // create atom based on provider
+      const atom =
+        provider === 'anthropic'
+          ? genAtomAnthropic({ model })
+          : provider === 'openai'
+            ? genAtomOpenai({ model })
+            : genAtomQwen({ model });
+
+      const actor = new BrainArch1Actor({
+        atom,
+        toolboxes: [toolboxFiles],
+        memory: null,
+        permission: permissionGuardReadOnly,
+        constraints: {
+          maxIterations: 100,
+          maxTokens: 8192,
+        },
+        role: {
+          systemPrompt: null,
+        },
+      });
+
+      return {
+        caller: await enrollThread({
+          role: 'caller',
+          stash: {
+            ask: input.ask,
+            art: {
+              result: genArtifactGitFile(
+                { uri: input.target },
+                { versions: true },
+              ),
+              log: genArtifactGitFile(
+                { uri: obsDir + '.log.md' },
+                { versions: true },
+              ),
+            },
+          },
+        }),
+        brain: await enrollThread({
+          role: 'brain',
+          stash: {
+            actor,
+            systemPromptPath: input.system ?? null,
+          },
+        }),
+      };
+    },
+  },
+  context: {
+    lookup: {
+      apiKeyAnthropic: {
+        source: 'process.env',
+        envar: 'ANTHROPIC_API_KEY',
+        desc: 'the anthropic api key',
+        type: '?string',
+      },
+      apiKeyOpenai: {
+        source: 'process.env',
+        envar: 'OPENAI_API_KEY',
+        desc: 'the openai api key',
+        type: '?string',
+      },
+      apiKeyQwen: {
+        source: 'process.env',
+        envar: 'QWEN_API_KEY',
+        desc: 'the qwen api key',
+        type: '?string',
+      },
+      apiKeyTavily: {
+        source: 'process.env',
+        envar: 'TAVILY_API_KEY',
+        desc: 'the tavily api key for web search',
+        type: '?string',
+      },
+    },
+    assess: (
+      input,
+    ): input is {
+      apiKeyAnthropic: string;
+      apiKeyOpenai: string;
+      apiKeyQwen: string;
+      apiKeyTavily: string;
+    } => true,
+    instantiate: (input: {
+      apiKeyAnthropic: string;
+      apiKeyOpenai: string;
+      apiKeyQwen: string;
+      apiKeyTavily: string;
+    }) => {
+      return {
+        creds: {
+          anthropic: { apiKey: input.apiKeyAnthropic ?? '', url: null },
+          openai: { apiKey: input.apiKeyOpenai ?? '', url: null },
+          qwen: { apiKey: input.apiKeyQwen ?? '', url: null },
+          tavily: { apiKey: input.apiKeyTavily ?? '' },
+        },
+        ...genContextLogTrail(),
+        ...genContextStitchTrail(),
+      };
+    },
+  },
+  readme: `
+# act
+
+invokes the agentic brain loop to complete a task
+
+## usage
+
+\`\`\`bash
+npx rhachet skills run act -t ./output.md "your task here"
+\`\`\`
+  `.trim(),
+});

package/dist/roles/brain/skills/act/stepAct.d.ts

@@ -0,0 +1,27 @@
+import { type GStitcher, type RoleContext, type Threads } from 'rhachet';
+import type { Artifact } from 'rhachet-artifact';
+import type { GitFile } from 'rhachet-artifact-git';
+import type { BrainArch1Actor } from '../../../../domain.objects/BrainArch1/BrainArch1Actor';
+import type { BrainArch1Context } from '../../../../domain.objects/BrainArch1/BrainArch1Context';
+/**
+ * .what = stitcher type for the act skill
+ * .why = defines the input/output contract for agentic task completion
+ */
+export type StitcherAct = GStitcher<Threads<{
+    caller: RoleContext<'caller', {
+        ask: string;
+        art: {
+            result: Artifact<typeof GitFile>;
+            log: Artifact<typeof GitFile>;
+        };
+    }>;
+    brain: RoleContext<'brain', {
+        actor: BrainArch1Actor;
+        systemPromptPath: string | null;
+    }>;
+}>, BrainArch1Context & GStitcher['context']>;
+/**
+ * .what = executes agentic task completion via brain invocation
+ * .why = enables llm with tools to autonomously complete tasks
+ */
+export declare const stepAct: import("rhachet").Stitcher<StitcherAct>;

package/dist/roles/brain/skills/act/stepAct.js

@@ -0,0 +1,95 @@
+"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.stepAct = void 0;
+const fs = __importStar(require("fs/promises"));
+const rhachet_1 = require("rhachet");
+const invokeBrainArch1_1 = require("../../../../domain.operations/brain.replic.arch1/core/invokeBrainArch1");
+/**
+ * .what = step to invoke brain and persist results
+ * .why = core step for agentic task completion
+ */
+const stepInvokeBrain = new rhachet_1.StitchStepCompute({
+    form: 'COMPUTE',
+    readme: 'invokes brain agentic loop and persists results',
+    slug: '@[brain]<act>',
+    stitchee: 'brain',
+    invoke: async ({ threads }, context) => {
+        const { caller, brain } = threads;
+        // load custom system prompt if specified
+        let systemPrompt = brain.context.stash.actor.role.systemPrompt;
+        if (brain.context.stash.systemPromptPath) {
+            systemPrompt = await fs.readFile(brain.context.stash.systemPromptPath, 'utf-8');
+        }
+        // invoke the brain
+        const result = await (0, invokeBrainArch1_1.invokeBrainArch1)({
+            actor: {
+                ...brain.context.stash.actor,
+                role: {
+                    ...brain.context.stash.actor.role,
+                    systemPrompt,
+                },
+            },
+            userInput: caller.context.stash.ask,
+        }, context);
+        // write result to output artifact
+        await caller.context.stash.art.result.set({
+            content: result.finalResponse ?? '',
+        });
+        // write execution log to log artifact
+        const logContent = [
+            `# brain act execution log`,
+            '',
+            `## summary`,
+            `- termination: ${result.terminationReason}`,
+            `- iterations: ${result.iterationCount}`,
+            `- tokens: ${result.totalTokenUsage.totalTokens}`,
+            '',
+            `## final response`,
+            '```',
+            result.finalResponse ?? '(no response)',
+            '```',
+            '',
+            result.error ? `## error\n${result.error}` : '',
+        ]
+            .filter(Boolean)
+            .join('\n');
+        await caller.context.stash.art.log.set({ content: logContent });
+        return {
+            input: { ask: caller.context.stash.ask },
+            output: { content: result.finalResponse ?? '' },
+        };
+    },
+});
+/**
+ * .what = executes agentic task completion via brain invocation
+ * .why = enables llm with tools to autonomously complete tasks
+ */
+exports.stepAct = (0, rhachet_1.asStitcherFlat)((0, rhachet_1.genStitchRoute)({
+    slug: '@[brain]<act>',
+    readme: '@[brain]<act> -> agentic task completion',
+    sequence: [stepInvokeBrain],
+}));
+//# sourceMappingURL=stepAct.js.map

package/dist/roles/brain/skills/act/stepAct.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stepAct.js","sourceRoot":"","sources":["../../../../../src/roles/brain/skills/act/stepAct.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;AAAA,gDAAkC;AAClC,qCAOiB;AAMjB,sGAAmG;AA6BnG;;;GAGG;AACH,MAAM,eAAe,GAAG,IAAI,2BAAiB,CAAc;IACzD,IAAI,EAAE,SAAS;IACf,MAAM,EAAE,iDAAiD;IACzD,IAAI,EAAE,eAAe;IACrB,QAAQ,EAAE,OAAO;IACjB,MAAM,EAAE,KAAK,EAAE,EAAE,OAAO,EAAE,EAAE,OAAO,EAAE,EAAE;QACrC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,OAAO,CAAC;QAElC,yCAAyC;QACzC,IAAI,YAAY,GAAG,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,YAAY,CAAC;QAC/D,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,gBAAgB,EAAE,CAAC;YACzC,YAAY,GAAG,MAAM,EAAE,CAAC,QAAQ,CAC9B,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,gBAAgB,EACpC,OAAO,CACR,CAAC;QACJ,CAAC;QAED,mBAAmB;QACnB,MAAM,MAAM,GAAG,MAAM,IAAA,mCAAgB,EACnC;YACE,KAAK,EAAE;gBACL,GAAG,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,KAAK;gBAC5B,IAAI,EAAE;oBACJ,GAAG,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI;oBACjC,YAAY;iBACb;aACF;YACD,SAAS,EAAE,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,GAAG;SACpC,EACD,OAAO,CACR,CAAC;QAEF,kCAAkC;QAClC,MAAM,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC;YACxC,OAAO,EAAE,MAAM,CAAC,aAAa,IAAI,EAAE;SACpC,CAAC,CAAC;QAEH,sCAAsC;QACtC,MAAM,UAAU,GAAG;YACjB,2BAA2B;YAC3B,EAAE;YACF,YAAY;YACZ,kBAAkB,MAAM,CAAC,iBAAiB,EAAE;YAC5C,iBAAiB,MAAM,CAAC,cAAc,EAAE;YACxC,aAAa,MAAM,CAAC,eAAe,CAAC,WAAW,EAAE;YACjD,EAAE;YACF,mBAAmB;YACnB,KAAK;YACL,MAAM,CAAC,aAAa,IAAI,eAAe;YACvC,KAAK;YACL,EAAE;YACF,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,aAAa,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE;SAChD;aACE,MAAM,CAAC,OAAO,CAAC;aACf,IAAI,CAAC,IAAI,CAAC,CAAC;QAEd,MAAM,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,OAAO,EAAE,UAAU,EAAE,CAAC,CAAC;QAEhE,OAAO;YACL,KAAK,EAAE,EAAE,GAAG,EAAE,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,GAAG,EAAE;YACxC,MAAM,EAAE,EAAE,OAAO,EAAE,MAAM,CAAC,aAAa,IAAI,EAAE,EAAE;SAChD,CAAC;IACJ,CAAC;CACF,CAAC,CAAC;AAEH;;;GAGG;AACU,QAAA,OAAO,GAAG,IAAA,wBAAc,EACnC,IAAA,wBAAc,EAAC;IACb,IAAI,EAAE,eAAe;IACrB,MAAM,EAAE,0CAA0C;IAClD,QAAQ,EAAE,CAAC,eAAe,CAAC;CAC5B,CAAC,CACH,CAAC"}