rhachet 1.18.0 → 1.19.0

package/dist/domain.objects/Actor.d.ts

@@ -0,0 +1,94 @@
+import { DomainEntity } from 'domain-objects';
+import type { z } from 'zod';
+import type { BrainRepl } from './BrainRepl';
+import type { Role, RoleSkillSchema } from './Role';
+/**
+ * .what = extracts skill input type from a RoleSkillSchema
+ * .why = enables type inference for skill arguments
+ */
+export type SkillInput<TSchema extends RoleSkillSchema> = z.infer<TSchema['input']>;
+/**
+ * .what = extracts skill output type from a RoleSkillSchema
+ * .why = enables type inference for skill return values
+ */
+export type SkillOutput<TSchema extends RoleSkillSchema> = z.infer<TSchema['output']>;
+/**
+ * .what = type for actor.act() method
+ * .why = enables type-safe rigid skill invocation
+ */
+export type ActorActOp<TRole extends Role> = <TSkillSlug extends keyof NonNullable<TRole['skills']['rigid']>>(input: {
+    brain?: {
+        repo: string;
+        slug: string;
+    } | BrainRepl;
+    skill: {
+        [K in TSkillSlug]: SkillInput<NonNullable<TRole['skills']['rigid']>[K]>;
+    };
+}) => Promise<SkillOutput<NonNullable<TRole['skills']['rigid']>[TSkillSlug]>>;
+/**
+ * .what = type for actor.run() method
+ * .why = enables type-safe solid skill invocation
+ */
+export type ActorRunOp<TRole extends Role> = <TSkillSlug extends keyof NonNullable<TRole['skills']['solid']>>(input: {
+    skill: {
+        [K in TSkillSlug]: SkillInput<NonNullable<TRole['skills']['solid']>[K]>;
+    };
+}) => Promise<SkillOutput<NonNullable<TRole['skills']['solid']>[TSkillSlug]>>;
+/**
+ * .what = type for actor.ask() method
+ * .why = enables fluid conversation with brain
+ */
+export type ActorAskOp = (input: {
+    prompt: string;
+}) => Promise<{
+    response: string;
+}>;
+/**
+ * .what = a role assumed by a brain, ready for invocation
+ * .why =
+ *   - enables sdk users to import and invoke actors directly
+ *   - composes role (skills + briefs) with brain allowlist
+ *   - provides type-safe .act(), .run(), .ask() methods
+ *
+ * .note = Actor = BrainRepl + Role composition
+ *   - first brain in allowlist is the default
+ *   - .act() invokes rigid skills (deterministic harness, brain operations)
+ *   - .run() invokes solid skills (deterministic, no brain)
+ *   - .ask() starts fluid conversation with default brain
+ */
+export interface Actor<TRole extends Role = Role> {
+    /**
+     * .what = the role this actor assumes
+     */
+    role: TRole;
+    /**
+     * .what = the brains this actor is allowed to use
+     * .note = first brain is the default
+     */
+    brains: BrainRepl[];
+    /**
+     * .what = invokes a rigid skill with brain
+     * .why = deterministic harness with probabilistic brain operations
+     */
+    act: ActorActOp<TRole>;
+    /**
+     * .what = invokes a solid skill via spawn
+     * .why = deterministic shell execution, no brain
+     */
+    run: ActorRunOp<TRole>;
+    /**
+     * .what = starts a fluid conversation with the default brain
+     * .why = open-ended exploration, brain decides path
+     */
+    ask: ActorAskOp;
+}
+export declare class Actor<TRole extends Role = Role> extends DomainEntity<Actor<TRole>> implements Actor<TRole> {
+    static unique: readonly ["role.slug"];
+    /**
+     * .what = creates an Actor with preserved literal skill types from TRole
+     * .why = enables type-safe .act(), .run(), .ask() invocation
+     *
+     * .note = use Actor.typed() instead of raw object cast for proper type preservation
+     */
+    static typed<TRole extends Role>(input: Actor<TRole>): Actor<TRole>;
+}

package/dist/domain.objects/Actor.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Actor = void 0;
+const domain_objects_1 = require("domain-objects");
+class Actor extends domain_objects_1.DomainEntity {
+    /**
+     * .what = creates an Actor with preserved literal skill types from TRole
+     * .why = enables type-safe .act(), .run(), .ask() invocation
+     *
+     * .note = use Actor.typed() instead of raw object cast for proper type preservation
+     */
+    static typed(input) {
+        return new Actor(input);
+    }
+}
+exports.Actor = Actor;
+Actor.unique = ['role.slug'];
+//# sourceMappingURL=Actor.js.map

package/dist/domain.objects/Actor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Actor.js","sourceRoot":"","sources":["../../src/domain.objects/Actor.ts"],"names":[],"mappings":";;;AAAA,mDAA8C;AAmG9C,MAAa,KACX,SAAQ,6BAA0B;IAKlC;;;;;OAKG;IACI,MAAM,CAAC,KAAK,CAAqB,KAAmB;QACzD,OAAO,IAAI,KAAK,CAAQ,KAAK,CAAC,CAAC;IACjC,CAAC;;AAdH,sBAeC;AAXe,YAAM,GAAG,CAAC,WAAW,CAAU,CAAC"}

package/dist/domain.objects/ActorRoleSkill.d.ts

@@ -0,0 +1,41 @@
+import { DomainLiteral } from 'domain-objects';
+import type { RoleSkillSchema } from './Role';
+import type { RoleSkillExecutable } from './RoleSkillExecutable';
+/**
+ * .what = a role skill that has been resolved and can be acted upon
+ * .why =
+ *   - unified return type for skill resolution
+ *   - explicit domain object for skill invocation
+ *   - actors use this to invoke skills via .act() and .run()
+ *
+ * .note = executable is required; ActorRoleSkill is only constructable
+ *   when a skill executable has been found
+ */
+export interface ActorRoleSkill {
+    /**
+     * .what = the skill's slug identifier
+     */
+    slug: string;
+    /**
+     * .what = the thought route for this skill
+     * .note = solid = deterministic, rigid = brain-augmented
+     */
+    route: 'solid' | 'rigid';
+    /**
+     * .what = where this skill was resolved from
+     * .note = role.skills takes precedence over .agent/ discovery
+     */
+    source: 'role.skills' | '.agent/';
+    /**
+     * .what = the zod schema for input/output validation
+     * .note = required; skills must have schemas to be executable via actor contracts
+     */
+    schema: RoleSkillSchema;
+    /**
+     * .what = the executable file for this skill
+     * .note = required; skill cannot be acted upon without an executable
+     */
+    executable: RoleSkillExecutable;
+}
+export declare class ActorRoleSkill extends DomainLiteral<ActorRoleSkill> implements ActorRoleSkill {
+}

package/dist/domain.objects/ActorRoleSkill.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ActorRoleSkill = void 0;
+const domain_objects_1 = require("domain-objects");
+class ActorRoleSkill extends domain_objects_1.DomainLiteral {
+}
+exports.ActorRoleSkill = ActorRoleSkill;
+//# sourceMappingURL=ActorRoleSkill.js.map

package/dist/domain.objects/ActorRoleSkill.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ActorRoleSkill.js","sourceRoot":"","sources":["../../src/domain.objects/ActorRoleSkill.ts"],"names":[],"mappings":";;;AAAA,mDAA+C;AA6C/C,MAAa,cACX,SAAQ,8BAA6B;CACT;AAF9B,wCAE8B"}

package/dist/domain.objects/InvokeHooks.d.ts

@@ -1,5 +1,31 @@
+import type { z } from 'zod';
 import type { InvokeOpts } from '.';
-export interface InvokeHooks {
+import type { Role, RoleSkillRegistry } from './Role';
+/**
+ * .what = extracts input type for a single skill from a skill registry
+ * .why = enables type inference for skill inputs in hooks
+ */
+type SkillInputFromRegistry<TRegistry extends RoleSkillRegistry, TSkill extends keyof TRegistry> = z.infer<TRegistry[TSkill]['input']>;
+/**
+ * .what = union type of all skill inputs from a registry
+ * .why = enables onInvokeActInput to accept any valid skill input
+ */
+type AnySkillInputFromRegistry<TRegistry extends RoleSkillRegistry> = {
+    [K in keyof TRegistry]: {
+        skill: K;
+        input: SkillInputFromRegistry<TRegistry, K>;
+    };
+}[keyof TRegistry];
+/**
+ * .what = hooks for customizing invoke behavior
+ * .why = enables input transformation before skill execution
+ *
+ * .note = generic TRole enables type-safe onInvokeActInput when Role.typed() is used
+ */
+export interface InvokeHooks<TRole extends Role = Role> {
+    /**
+     * .what = transforms ask input before execution
+     */
     onInvokeAskInput: Array<(input: InvokeOpts<{
         ask: string;
         config: string;
@@ -7,4 +33,15 @@ export interface InvokeHooks {
         ask: string;
         config: string;
     }>>;
+    /**
+     * .what = transforms act input before skill execution
+     * .why = enables input manipulation (e.g., adding defaults, validation)
+     *
+     * .note = strongly typed when TRole preserves literal skill names via Role.typed()
+     */
+    onInvokeActInput?: TRole['skills']['rigid'] extends RoleSkillRegistry ? (input: AnySkillInputFromRegistry<NonNullable<TRole['skills']['rigid']>>) => AnySkillInputFromRegistry<NonNullable<TRole['skills']['rigid']>>['input'] : (input: {
+        skill: string;
+        input: Record<string, unknown>;
+    }) => Record<string, unknown>;
 }
+export {};

package/dist/domain.objects/Role.d.ts

@@ -1,13 +1,33 @@
 import { DomainEntity } from 'domain-objects';
+import type { z } from 'zod';
 import type { RoleSkill } from './RoleSkill';
 import type { RoleTrait } from './RoleTrait';
+/**
+ * .what = type definition for a skill's schema (input/output zod schemas)
+ * .why = enables type-safe skill invocation via .act() and .run()
+ */
+export interface RoleSkillSchema {
+    input: z.ZodSchema;
+    output: z.ZodSchema;
+}
+/**
+ * .what = type for a record of skills with literal keys preserved
+ * .why = enables type inference of skill names via keyof
+ */
+export type RoleSkillRegistry = {
+    readonly [slug: string]: RoleSkillSchema;
+};
 /**
  * .what = defines a role that can have traits, know skills, and be instantiated across thread.context
  * .why =
  *   - enables registration of usable roles (e.g., 'mechanic', 'designer', 'architect', 'ecologist')
  *   - enables instantiation of thread.contexts
+ *
+ * .note = generic type parameters preserve literal skill names for type-safe invocation
+ *   - TSolid: the solid skills record type (e.g., { 'wordcount': { input, output } })
+ *   - TRigid: the rigid skills record type (e.g., { 'review': { input, output } })
  */
-export interface Role {
+export interface Role<TSolid extends RoleSkillRegistry = RoleSkillRegistry, TRigid extends RoleSkillRegistry = RoleSkillRegistry> {
     /**
      * .what = a unique, readable identifier
      * .example = "mechanic"
@@ -40,12 +60,26 @@ export interface Role {
      * .what = the skills known by the role
      * .why = declares what the role can do
      * .how =
+     *   - solid: typed skills for deterministic execution (no brain)
+     *     - enables type-safe .run() invocation
+     *   - rigid: typed skills for deterministic harness with brain operations
+     *     - enables type-safe .act() invocation
      *   - dirs: directory-based skills (e.g., .sh scripts) for linking/booting
      *     - single { uri: string }: symlinks this dir as the full skills dir
      *     - array { uri: string }[]: symlinks each dir within the skills dir
      *   - refs: programmatic RoleSkill references for execution
      */
     skills: {
+        /**
+         * .what = solid skills (deterministic, no brain)
+         * .why = type-safe .run() invocation
+         */
+        solid?: TSolid;
+        /**
+         * .what = rigid skills (deterministic harness, brain operations)
+         * .why = type-safe .act() invocation
+         */
+        rigid?: TRigid;
         dirs: {
             uri: string;
         } | {
@@ -89,6 +123,13 @@ export interface Role {
         }[];
     };
 }
-export declare class Role extends DomainEntity<Role> implements Role {
+export declare class Role<TSolid extends RoleSkillRegistry = RoleSkillRegistry, TRigid extends RoleSkillRegistry = RoleSkillRegistry> extends DomainEntity<Role<TSolid, TRigid>> implements Role<TSolid, TRigid> {
     static unique: readonly ["slug"];
+    /**
+     * .what = creates a Role with preserved literal skill names
+     * .why = enables type-safe skill invocation via genActor
+     *
+     * .note = use Role.typed() instead of new Role() to preserve literal types
+     */
+    static typed<TSolid extends RoleSkillRegistry, TRigid extends RoleSkillRegistry>(input: Role<TSolid, TRigid>): Role<TSolid, TRigid>;
 }

package/dist/domain.objects/Role.js

@@ -3,6 +3,15 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.Role = void 0;
 const domain_objects_1 = require("domain-objects");
 class Role extends domain_objects_1.DomainEntity {
+    /**
+     * .what = creates a Role with preserved literal skill names
+     * .why = enables type-safe skill invocation via genActor
+     *
+     * .note = use Role.typed() instead of new Role() to preserve literal types
+     */
+    static typed(input) {
+        return new Role(input);
+    }
 }
 exports.Role = Role;
 Role.unique = ['slug'];

package/dist/domain.objects/Role.js.map

@@ -1 +1 @@
-{"version":3,"file":"Role.js","sourceRoot":"","sources":["../../src/domain.objects/Role.ts"],"names":[],"mappings":";;;AAAA,mDAA8C;AAoF9C,MAAa,IAAK,SAAQ,6BAAkB;;AAA5C,oBAEC;AADe,WAAM,GAAG,CAAC,MAAM,CAAU,CAAC"}
+{"version":3,"file":"Role.js","sourceRoot":"","sources":["../../src/domain.objects/Role.ts"],"names":[],"mappings":";;;AAAA,mDAA8C;AA2H9C,MAAa,IAIX,SAAQ,6BAAkC;IAK1C;;;;;OAKG;IACI,MAAM,CAAC,KAAK,CAGjB,KAA2B;QAC3B,OAAO,IAAI,IAAI,CAAiB,KAAK,CAAC,CAAC;IACzC,CAAC;;AApBH,oBAqBC;AAde,WAAM,GAAG,CAAC,MAAM,CAAU,CAAC"}

package/dist/domain.objects/index.d.ts

@@ -9,6 +9,8 @@ export * from './StitchStep';
 export * from './StitchTrail';
 export * from './Thread';
 export * from './Threads';
+export * from './Actor';
+export * from './ActorRoleSkill';
 export * from './BrainAtom';
 export * from './BrainRepl';
 export * from './ContextBrain';

package/dist/domain.objects/index.js

@@ -27,6 +27,8 @@ __exportStar(require("./Thread"), exports);
 __exportStar(require("./Threads"), exports);
 // export * from './Weave';
 // export * from './Weaver';
+__exportStar(require("./Actor"), exports);
+__exportStar(require("./ActorRoleSkill"), exports);
 __exportStar(require("./BrainAtom"), exports);
 __exportStar(require("./BrainRepl"), exports);
 __exportStar(require("./ContextBrain"), exports);

package/dist/domain.objects/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/domain.objects/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,2CAAyB;AACzB,iDAA+B;AAC/B,gDAA8B;AAC9B,6CAA2B;AAC3B,iDAA+B;AAC/B,gDAA8B;AAC9B,mDAAiC;AACjC,+CAA6B;AAC7B,gDAA8B;AAC9B,2CAAyB;AACzB,4CAA0B;AAE1B,2BAA2B;AAC3B,4BAA4B;AAE5B,8CAA4B;AAC5B,8CAA4B;AAC5B,iDAA+B;AAC/B,gDAA8B;AAC9B,+CAA6B;AAC7B,yCAAuB;AACvB,gDAA8B;AAC9B,iDAA+B;AAC/B,8CAA4B;AAC5B,uDAAqC;AACrC,wDAAsC;AACtC,8CAA4B;AAC5B,6CAA2B"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/domain.objects/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,2CAAyB;AACzB,iDAA+B;AAC/B,gDAA8B;AAC9B,6CAA2B;AAC3B,iDAA+B;AAC/B,gDAA8B;AAC9B,mDAAiC;AACjC,+CAA6B;AAC7B,gDAA8B;AAC9B,2CAAyB;AACzB,4CAA0B;AAE1B,2BAA2B;AAC3B,4BAA4B;AAE5B,0CAAwB;AACxB,mDAAiC;AACjC,8CAA4B;AAC5B,8CAA4B;AAC5B,iDAA+B;AAC/B,gDAA8B;AAC9B,+CAA6B;AAC7B,yCAAuB;AACvB,gDAA8B;AAC9B,iDAA+B;AAC/B,8CAA4B;AAC5B,uDAAqC;AACrC,wDAAsC;AACtC,8CAA4B;AAC5B,6CAA2B"}

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

@@ -0,0 +1,15 @@
+import type { ActorRoleSkill } from '../../domain.objects/ActorRoleSkill';
+import type { BrainRepl } from '../../domain.objects/BrainRepl';
+import type { Role } from '../../domain.objects/Role';
+/**
+ * .what = executes a rigid skill with a brain
+ * .why = deterministic harness with probabilistic brain operations
+ *
+ * .note = skill is pre-resolved by genActor; this just executes
+ */
+export declare const actorAct: (input: {
+    role: Role;
+    brain: BrainRepl;
+    skill: ActorRoleSkill;
+    args: Record<string, unknown>;
+}) => Promise<unknown>;

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

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.actorAct = void 0;
+const getRoleBriefs_1 = require("../../domain.operations/role/getRoleBriefs");
+/**
+ * .what = executes a rigid skill with a brain
+ * .why = deterministic harness with probabilistic brain operations
+ *
+ * .note = skill is pre-resolved by genActor; this just executes
+ */
+const actorAct = async (input) => {
+    // resolve briefs from role
+    const briefs = await (0, getRoleBriefs_1.getRoleBriefs)({
+        by: {
+            role: { name: input.role.slug },
+            briefs: { glob: '**/*' },
+        },
+    });
+    // execute rigid skill with brain
+    const result = await input.brain.act({
+        role: { briefs },
+        prompt: `Execute skill "${input.skill.slug}" with args: ${JSON.stringify(input.args)}`,
+        schema: {
+            output: input.skill.schema?.output ?? {},
+        },
+    });
+    return result;
+};
+exports.actorAct = actorAct;
+//# sourceMappingURL=actorAct.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"actorAct.js","sourceRoot":"","sources":["../../../src/domain.operations/actor/actorAct.ts"],"names":[],"mappings":";;;AAGA,6EAA0E;AAE1E;;;;;GAKG;AACI,MAAM,QAAQ,GAAG,KAAK,EAAE,KAK9B,EAAoB,EAAE;IACrB,2BAA2B;IAC3B,MAAM,MAAM,GAAG,MAAM,IAAA,6BAAa,EAAC;QACjC,EAAE,EAAE;YACF,IAAI,EAAE,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,IAAI,EAAE;YAC/B,MAAM,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE;SACzB;KACF,CAAC,CAAC;IAEH,iCAAiC;IACjC,MAAM,MAAM,GAAG,MAAM,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC;QACnC,IAAI,EAAE,EAAE,MAAM,EAAE;QAChB,MAAM,EAAE,kBAAkB,KAAK,CAAC,KAAK,CAAC,IAAI,gBAAgB,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE;QACtF,MAAM,EAAE;YACN,MAAM,EAAE,KAAK,CAAC,KAAK,CAAC,MAAM,EAAE,MAAM,IAAK,EAAU;SAClD;KACF,CAAC,CAAC;IAEH,OAAO,MAAM,CAAC;AAChB,CAAC,CAAC;AAxBW,QAAA,QAAQ,YAwBnB"}

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

@@ -0,0 +1,15 @@
+import type { BrainRepl } from '../../domain.objects/BrainRepl';
+import type { Role } from '../../domain.objects/Role';
+/**
+ * .what = starts a fluid conversation with a brain
+ * .why = open-ended exploration, brain decides path
+ *
+ * todo: support --interactive mode for cli invocations
+ */
+export declare const actorAsk: (input: {
+    role: Role;
+    brain: BrainRepl;
+    prompt: string;
+}) => Promise<{
+    response: string;
+}>;

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

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.actorAsk = void 0;
+const zod_1 = require("zod");
+const getRoleBriefs_1 = require("../../domain.operations/role/getRoleBriefs");
+/**
+ * .what = starts a fluid conversation with a brain
+ * .why = open-ended exploration, brain decides path
+ *
+ * todo: support --interactive mode for cli invocations
+ */
+const actorAsk = async (input) => {
+    // resolve briefs from role
+    const briefs = await (0, getRoleBriefs_1.getRoleBriefs)({
+        by: {
+            role: { name: input.role.slug },
+            briefs: { glob: '**/*' },
+        },
+    });
+    // execute fluid conversation with brain
+    // note: openai requires object schema, so wrap response in object
+    const result = await input.brain.ask({
+        role: { briefs },
+        prompt: input.prompt,
+        schema: {
+            output: zod_1.z.object({ response: zod_1.z.string() }),
+        },
+    });
+    return result;
+};
+exports.actorAsk = actorAsk;
+//# sourceMappingURL=actorAsk.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"actorAsk.js","sourceRoot":"","sources":["../../../src/domain.operations/actor/actorAsk.ts"],"names":[],"mappings":";;;AAAA,6BAAwB;AAIxB,6EAA0E;AAE1E;;;;;GAKG;AACI,MAAM,QAAQ,GAAG,KAAK,EAAE,KAI9B,EAAiC,EAAE;IAClC,2BAA2B;IAC3B,MAAM,MAAM,GAAG,MAAM,IAAA,6BAAa,EAAC;QACjC,EAAE,EAAE;YACF,IAAI,EAAE,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,IAAI,EAAE;YAC/B,MAAM,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE;SACzB;KACF,CAAC,CAAC;IAEH,wCAAwC;IACxC,kEAAkE;IAClE,MAAM,MAAM,GAAG,MAAM,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC;QACnC,IAAI,EAAE,EAAE,MAAM,EAAE;QAChB,MAAM,EAAE,KAAK,CAAC,MAAM;QACpB,MAAM,EAAE;YACN,MAAM,EAAE,OAAC,CAAC,MAAM,CAAC,EAAE,QAAQ,EAAE,OAAC,CAAC,MAAM,EAAE,EAAE,CAAC;SAC3C;KACF,CAAC,CAAC;IAEH,OAAO,MAAM,CAAC;AAChB,CAAC,CAAC;AAxBW,QAAA,QAAQ,YAwBnB"}

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

@@ -0,0 +1,11 @@
+import type { ActorRoleSkill } from '../../domain.objects/ActorRoleSkill';
+/**
+ * .what = executes a solid skill via spawn
+ * .why = deterministic shell execution, no brain
+ *
+ * .note = skill is pre-resolved by genActor; this just executes
+ */
+export declare const actorRun: (input: {
+    skill: ActorRoleSkill;
+    args: Record<string, unknown>;
+}) => Promise<unknown>;

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

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.actorRun = void 0;
+const executeSkill_1 = require("../../domain.operations/invoke/executeSkill");
+/**
+ * .what = executes a solid skill via spawn
+ * .why = deterministic shell execution, no brain
+ *
+ * .note = skill is pre-resolved by genActor; this just executes
+ */
+const actorRun = async (input) => {
+    // convert skill args object to CLI args array
+    const argsArray = [];
+    for (const [key, value] of Object.entries(input.args)) {
+        argsArray.push(`--${key}`, String(value));
+    }
+    // execute skill via spawn
+    const result = await (0, executeSkill_1.executeSkill)({
+        skill: input.skill.executable,
+        args: argsArray,
+    });
+    return result;
+};
+exports.actorRun = actorRun;
+//# sourceMappingURL=actorRun.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"actorRun.js","sourceRoot":"","sources":["../../../src/domain.operations/actor/actorRun.ts"],"names":[],"mappings":";;;AACA,6EAA0E;AAE1E;;;;;GAKG;AACI,MAAM,QAAQ,GAAG,KAAK,EAAE,KAG9B,EAAoB,EAAE;IACrB,8CAA8C;IAC9C,MAAM,SAAS,GAAa,EAAE,CAAC;IAC/B,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;QACtD,SAAS,CAAC,IAAI,CAAC,KAAK,GAAG,EAAE,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;IAC5C,CAAC;IAED,0BAA0B;IAC1B,MAAM,MAAM,GAAG,MAAM,IAAA,2BAAY,EAAC;QAChC,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC,UAAU;QAC7B,IAAI,EAAE,SAAS;KAChB,CAAC,CAAC;IAEH,OAAO,MAAM,CAAC;AAChB,CAAC,CAAC;AAjBW,QAAA,QAAQ,YAiBnB"}

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

@@ -0,0 +1,16 @@
+import type { BrainRepl } from '../../domain.objects/BrainRepl';
+/**
+ * .what = finds a brain in the actor's allowlist
+ * .why = validates that a requested brain is permitted by the actor
+ *
+ * .note = accepts either:
+ *   - ref: { repo, slug } for lookup by unique key
+ *   - direct BrainRepl instance for validation against allowlist
+ */
+export declare const findActorBrainInAllowlist: (input: {
+    brain: {
+        repo: string;
+        slug: string;
+    } | BrainRepl;
+    allowlist: BrainRepl[];
+}) => BrainRepl;

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

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.findActorBrainInAllowlist = void 0;
+const helpful_errors_1 = require("helpful-errors");
+/**
+ * .what = finds a brain in the actor's allowlist
+ * .why = validates that a requested brain is permitted by the actor
+ *
+ * .note = accepts either:
+ *   - ref: { repo, slug } for lookup by unique key
+ *   - direct BrainRepl instance for validation against allowlist
+ */
+const findActorBrainInAllowlist = (input) => {
+    // extract repo and slug from brain (whether ref or instance)
+    const brainRef = {
+        repo: input.brain.repo,
+        slug: input.brain.slug,
+    };
+    // lookup brain in allowlist by unique key
+    const brainFound = input.allowlist.find((b) => b.repo === brainRef.repo && b.slug === brainRef.slug);
+    // fail if brain not in allowlist
+    if (!brainFound)
+        throw new helpful_errors_1.BadRequestError('brain not in actor allowlist', {
+            brainRef,
+            allowlistRefs: input.allowlist.map((b) => ({
+                repo: b.repo,
+                slug: b.slug,
+            })),
+        });
+    return brainFound;
+};
+exports.findActorBrainInAllowlist = findActorBrainInAllowlist;
+//# sourceMappingURL=findActorBrainInAllowlist.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"findActorBrainInAllowlist.js","sourceRoot":"","sources":["../../../src/domain.operations/actor/findActorBrainInAllowlist.ts"],"names":[],"mappings":";;;AAAA,mDAAiD;AAIjD;;;;;;;GAOG;AACI,MAAM,yBAAyB,GAAG,CAAC,KAGzC,EAAa,EAAE;IACd,6DAA6D;IAC7D,MAAM,QAAQ,GAAG;QACf,IAAI,EAAE,KAAK,CAAC,KAAK,CAAC,IAAI;QACtB,IAAI,EAAE,KAAK,CAAC,KAAK,CAAC,IAAI;KACvB,CAAC;IAEF,0CAA0C;IAC1C,MAAM,UAAU,GAAG,KAAK,CAAC,SAAS,CAAC,IAAI,CACrC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,QAAQ,CAAC,IAAI,IAAI,CAAC,CAAC,IAAI,KAAK,QAAQ,CAAC,IAAI,CAC5D,CAAC;IAEF,iCAAiC;IACjC,IAAI,CAAC,UAAU;QACb,MAAM,IAAI,gCAAe,CAAC,8BAA8B,EAAE;YACxD,QAAQ;YACR,aAAa,EAAE,KAAK,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;gBACzC,IAAI,EAAE,CAAC,CAAC,IAAI;gBACZ,IAAI,EAAE,CAAC,CAAC,IAAI;aACb,CAAC,CAAC;SACJ,CAAC,CAAC;IAEL,OAAO,UAAU,CAAC;AACpB,CAAC,CAAC;AA1BW,QAAA,yBAAyB,6BA0BpC"}

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

@@ -0,0 +1,13 @@
+import { ActorRoleSkill } from '../../domain.objects/ActorRoleSkill';
+import type { Role } from '../../domain.objects/Role';
+/**
+ * .what = finds a skill by slug for a role
+ * .why = resolves skill from role.skills[route] or .agent/ dirs
+ *
+ * .note = role.skills[route] takes precedence over .agent/ dirs (usecase.8)
+ */
+export declare const findActorRoleSkillBySlug: (input: {
+    slug: string;
+    role: Role;
+    route: 'solid' | 'rigid';
+}) => ActorRoleSkill;

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

@@ -0,0 +1,68 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.findActorRoleSkillBySlug = void 0;
+const helpful_errors_1 = require("helpful-errors");
+const ActorRoleSkill_1 = require("../../domain.objects/ActorRoleSkill");
+const discoverSkillExecutables_1 = require("../../domain.operations/invoke/discoverSkillExecutables");
+/**
+ * .what = finds a skill by slug for a role
+ * .why = resolves skill from role.skills[route] or .agent/ dirs
+ *
+ * .note = role.skills[route] takes precedence over .agent/ dirs (usecase.8)
+ */
+const findActorRoleSkillBySlug = (input) => {
+    // check role.skills[route] first (takes precedence per usecase.8)
+    const skillsForRoute = input.route === 'solid' ? input.role.skills.solid : input.role.skills.rigid;
+    // lookup schema from role.skills[route]
+    const skillSchema = skillsForRoute?.[input.slug];
+    if (skillSchema) {
+        // find executable from .agent/ dirs (skill schema defines type, but executable runs)
+        const executables = (0, discoverSkillExecutables_1.discoverSkillExecutables)({
+            roleSlug: input.role.slug,
+            skillSlug: input.slug,
+        });
+        // fail fast if skill is declared but no executable found
+        if (executables.length === 0)
+            throw new helpful_errors_1.BadRequestError(`skill "${input.slug}" declared in role.skills.${input.route} but no executable found in .agent/`, {
+                skillSlug: input.slug,
+                roleSlug: input.role.slug,
+                route: input.route,
+                hint: `create .agent/repo=.this/role=${input.role.slug}/skills/${input.slug}.sh`,
+            });
+        return new ActorRoleSkill_1.ActorRoleSkill({
+            slug: input.slug,
+            route: input.route,
+            source: 'role.skills',
+            schema: skillSchema,
+            executable: executables[0],
+        });
+    }
+    // fall back to .agent/ discovery (executable exists but no schema)
+    const executables = (0, discoverSkillExecutables_1.discoverSkillExecutables)({
+        roleSlug: input.role.slug,
+        skillSlug: input.slug,
+    });
+    // executable exists but no schema = not usable via actor contracts
+    if (executables.length > 0)
+        throw new helpful_errors_1.BadRequestError(`skill "${input.slug}" found in .agent/ but lacks schema in role.skills.${input.route}`, {
+            skillSlug: input.slug,
+            roleSlug: input.role.slug,
+            route: input.route,
+            hint: `add schema to role.skills.${input.route}.${input.slug} to use via actor contracts`,
+            executable: executables[0],
+        });
+    // skill not found
+    throw new helpful_errors_1.BadRequestError(`skill not found: ${input.slug}`, {
+        skillSlug: input.slug,
+        roleSlug: input.role.slug,
+        route: input.route,
+        availableSolidSkills: input.role.skills.solid
+            ? Object.keys(input.role.skills.solid)
+            : [],
+        availableRigidSkills: input.role.skills.rigid
+            ? Object.keys(input.role.skills.rigid)
+            : [],
+    });
+};
+exports.findActorRoleSkillBySlug = findActorRoleSkillBySlug;
+//# sourceMappingURL=findActorRoleSkillBySlug.js.map

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

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