@rolexjs/prototype 1.4.0-dev-20260305012717 → 1.4.0-dev-20260305032702

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import { PrototypeData, PrototypeRepository } from '@rolexjs/core';
-import { State, Runtime, Structure } from '@rolexjs/system';
-import { IssueX } from 'issuexjs';
-import { ResourceX } from 'resourcexjs';
+import { Runtime, Structure, State } from '@rolexjs/system';
+import { IssueX, Issue, Comment } from 'issuexjs';
+import { ResourceX, Resource, RXM } from 'resourcexjs';
 
 /**
  * applyPrototype — apply a prototype's migrations incrementally.
@@ -26,6 +26,101 @@ interface ApplyResult {
  */
 declare function applyPrototype(data: PrototypeData, repo: PrototypeRepository, direct: (op: string, args: Record<string, unknown>) => Promise<unknown>): Promise<ApplyResult>;
 
+/**
+ * Commands — platform-agnostic command implementations.
+ *
+ * Every RoleX command is a pure function of (Runtime, args) → CommandResult.
+ * No platform-specific code — all I/O goes through injected interfaces.
+ *
+ * Usage:
+ *   const commands = createCommands({ rt, society, past, resolve, find, resourcex });
+ *   const result = commands["individual.born"]("Feature: Sean", "sean");
+ */
+
+interface CommandResult {
+    state: State;
+    process: string;
+}
+interface CommandContext {
+    rt: Runtime;
+    society: Structure;
+    past: Structure;
+    resolve(id: string): Structure | Promise<Structure>;
+    find(id: string): (Structure | null) | Promise<Structure | null>;
+    resourcex?: ResourceX;
+    issuex?: IssueX;
+    prototype?: PrototypeRepository;
+    direct?(locator: string, args?: Record<string, unknown>): Promise<unknown>;
+}
+/**
+ * CommandResultMap — typed return type for every command.
+ *
+ * This is the source of truth for what each command returns.
+ * Renderer and consumers use this to know the shape of each result.
+ */
+interface CommandResultMap {
+    "individual.born": CommandResult;
+    "individual.retire": CommandResult;
+    "individual.die": CommandResult;
+    "individual.rehire": CommandResult;
+    "individual.teach": CommandResult;
+    "individual.train": CommandResult;
+    "role.focus": CommandResult;
+    "role.want": CommandResult;
+    "role.plan": CommandResult;
+    "role.todo": CommandResult;
+    "role.finish": CommandResult;
+    "role.complete": CommandResult;
+    "role.abandon": CommandResult;
+    "role.reflect": CommandResult;
+    "role.realize": CommandResult;
+    "role.master": CommandResult;
+    "role.forget": CommandResult;
+    "role.skill": string;
+    "project.launch": CommandResult;
+    "project.scope": CommandResult;
+    "project.milestone": CommandResult;
+    "project.achieve": CommandResult;
+    "project.enroll": CommandResult;
+    "project.remove": CommandResult;
+    "project.deliver": CommandResult;
+    "project.wiki": CommandResult;
+    "project.archive": CommandResult;
+    "org.found": CommandResult;
+    "org.charter": CommandResult;
+    "org.dissolve": CommandResult;
+    "org.hire": CommandResult;
+    "org.fire": CommandResult;
+    "position.establish": CommandResult;
+    "position.charge": CommandResult;
+    "position.require": CommandResult;
+    "position.abolish": CommandResult;
+    "position.appoint": CommandResult;
+    "position.dismiss": CommandResult;
+    "census.list": CommandResult;
+    "issue.publish": Issue;
+    "issue.get": Issue | null;
+    "issue.list": Issue[];
+    "issue.update": Issue;
+    "issue.close": Issue;
+    "issue.reopen": Issue;
+    "issue.assign": Issue;
+    "issue.comment": Comment;
+    "issue.comments": Comment[];
+    "issue.label": Issue | null;
+    "issue.unlabel": Issue | null;
+    "resource.add": Resource;
+    "resource.search": string[];
+    "resource.has": boolean;
+    "resource.info": Resource;
+    "resource.remove": undefined;
+    "resource.push": RXM;
+    "resource.pull": undefined;
+    "resource.clearCache": undefined;
+}
+type Commands = Record<string, (...args: any[]) => any>;
+declare function createCommands(ctx: CommandContext): Commands;
+
 declare const processes: Record<string, string>;
 declare const world: Record<string, string>;
 
@@ -79,6 +174,15 @@ interface InstructionDef {
     /** Positional argument order — maps named args to method call positions. */
     args: readonly ArgEntry[];
 }
+/** RoleX tool definition — schema for a top-level tool (activate, want, use, etc.). */
+interface ToolDef {
+    /** Tool name (e.g. "activate", "use"). */
+    name: string;
+    /** Parameter definitions — keyed by param name. */
+    params: Record<string, ParamDef>;
+    /** Whether the tool accepts additional unnamed parameters (e.g. use/direct). */
+    additionalProperties?: boolean;
+}
 
 /**
  * Instruction set — schema definitions for all RoleX operations.
@@ -89,32 +193,41 @@ interface InstructionDef {
 declare const instructions: Record<string, InstructionDef>;
 
 /**
- * Ops — platform-agnostic operation implementations.
- *
- * Every RoleX operation is a pure function of (Runtime, args) → OpResult.
- * No platform-specific code — all I/O goes through injected interfaces.
+ * Renderer — framework for rendering command results.
  *
- * Usage:
- *   const ops = createOps({ rt, society, past, resolve, find, resourcex });
- *   const result = ops["individual.born"]("Feature: Sean", "sean");
+ * Renderer interface and RendererRouter live here in prototype
+ * because this layer owns all command types and structures.
+ * Concrete renderers are registered by the upper layer (rolexjs).
  */
 
-interface OpResult {
-    state: State;
-    process: string;
+/** Renders a command result into a string (typically Markdown). */
+interface Renderer {
+    render(command: string, result: CommandResult): string;
 }
-interface OpsContext {
-    rt: Runtime;
-    society: Structure;
-    past: Structure;
-    resolve(id: string): Structure | Promise<Structure>;
-    find(id: string): (Structure | null) | Promise<Structure | null>;
-    resourcex?: ResourceX;
-    issuex?: IssueX;
-    prototype?: PrototypeRepository;
-    direct?(locator: string, args?: Record<string, unknown>): Promise<unknown>;
+/**
+ * RendererRouter — routes commands to namespace-specific renderers.
+ *
+ * Registered renderers handle their namespace (e.g. "role" handles "role.want").
+ * Unregistered commands fall through to the default renderer (JSON serialization).
+ */
+declare class RendererRouter implements Renderer {
+    private readonly renderers;
+    /** Register a renderer for a command namespace. */
+    register(namespace: string, renderer: Renderer): this;
+    /** Route a command to the appropriate renderer. */
+    render(command: string, result: CommandResult): string;
 }
-type Ops = Record<string, (...args: any[]) => any>;
-declare function createOps(ctx: OpsContext): Ops;
 
-export { type ApplyResult, type ArgEntry, type InstructionDef, type OpResult, type Ops, type OpsContext, type ParamDef, type ParamType, applyPrototype, createOps, directives, instructions, processes, toArgs, world };
+/**
+ * RoleX tool definitions — the single source of truth for all tool schemas.
+ *
+ * Channel-agnostic: MCP, CLI, REST, A2A each convert to their own format.
+ * Description for each tool comes from descriptions/processes via detail().
+ * This file only defines the parameter schema.
+ */
+
+/** Pre-assembled world instructions — the cognitive framework for AI roles. */
+declare const worldInstructions: string;
+declare const tools: ToolDef[];
+
+export { type ApplyResult, type ArgEntry, type CommandContext, type CommandResult, type CommandResultMap, type Commands, type InstructionDef, type ParamDef, type ParamType, type Renderer, RendererRouter, type ToolDef, applyPrototype, createCommands, directives, instructions, processes, toArgs, tools, world, worldInstructions };