@frockbot/kernel-agent-loop 0.0.0 → 0.1.1

package/package.json

@@ -1,14 +1,34 @@
 {
   "name": "@frockbot/kernel-agent-loop",
-  "version": "0.0.0",
-  "description": "Placeholder reserving this name for trusted publishing. Superseded by the first release.",
-  "license": "UNLICENSED",
+  "version": "0.1.1",
+  "private": false,
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./agent": "./src/agent.ts"
+  },
+  "scripts": {
+    "test": "bun test src",
+    "typecheck": "tsc --noEmit -p tsconfig.json"
+  },
+  "dependencies": {
+    "@frockbot/kernel-contracts": "0.1.1",
+    "cordis": "4.0.0-rc.8"
+  },
+  "devDependencies": {
+    "@frockbot/plugin-models": "0.1.1",
+    "@frockbot/plugin-prompt": "0.1.1",
+    "@frockbot/plugin-tools": "0.1.1",
+    "@types/bun": "1.4.0",
+    "@types/node": "26.2.0",
+    "typescript": "^7.0.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/timoconnellaus/frockbot.git",
     "directory": "packages/kernel-agent-loop"
-  },
-  "publishConfig": {
-    "access": "public"
   }
 }

package/src/agent.ts

@@ -0,0 +1,172 @@
+import { type Context, Service } from "cordis";
+import type {
+  ModelBindingSnapshot,
+  NormalizedModelRequest,
+  Session,
+  SkillRefV1,
+  TurnTypeV1,
+} from "@frockbot/kernel-contracts";
+
+export type AgentStatus = "idle" | "running" | "disposed";
+
+/** One exact new external effect whose durable intent is already journaled. */
+export type AgentEffectAdmission =
+  { kind: "model"; effectId: string } | { kind: "tool"; effectId: string };
+
+export interface AgentOptions {
+  botId: string;
+  agentId?: string;
+  sessionId: string;
+  provider: string;
+  model: string;
+  /**
+   * The kind of Turn this Agent's runs are admitted as. It selects the tool
+   * catalog and nothing else; the kernel carries the value and holds no
+   * opinion about what any turn type admits. Defaults to `chat`, which is what
+   * every Turn recorded before turn admission existed replays as.
+   */
+  turnType?: TurnTypeV1;
+  /**
+   * The subagent role this Agent's runs are admitted under. A second ceiling
+   * dimension on the same terms as `turnType`: it selects the tool catalog and
+   * nothing else, and the kernel holds no opinion about what a role name
+   * means. Only meaningful on a `subagent` Turn; absent means no narrowing.
+   */
+  subagentRole?: string;
+  /** Durably linearizes each new effect against Stop immediately before use. */
+  admitEffect(effect: AgentEffectAdmission): Promise<boolean>;
+  modelBinding?: ModelBindingSnapshot;
+}
+
+export interface AgentInput {
+  messageId: string;
+  text: string;
+  /**
+   * The Skills this input invoked from the composer. The kernel carries the
+   * refs and resolves nothing: which Skill a ref names, and what happens to
+   * its body, is the Skills Package's policy, read off this field in
+   * `agent/pre-step`.
+   */
+  skills?: SkillRefV1[];
+}
+
+/** What `Agent.send` accepts: bare text, or text with invoked Skills. */
+export interface AgentSendV1 {
+  text: string;
+  skills?: readonly SkillRefV1[];
+}
+
+export type PreStepDecision =
+  { kind: "enter"; inputs: AgentInput[] } | { kind: "reject"; reason: string };
+
+export type RequestErrorAction = { kind: "retry" } | { kind: "fail" };
+
+export interface Agent {
+  readonly id: string;
+  readonly botId: string;
+  readonly session: Session;
+  readonly status: AgentStatus;
+  send(input: string | AgentSendV1): string;
+  resume(): void;
+  cancel(reason?: "user" | "shutdown"): void;
+  whenIdle(): Promise<void>;
+}
+
+export interface AgentHandle {
+  agent: Agent;
+  dispose(): Promise<void>;
+}
+
+export interface AgentFactory {
+  create(options: AgentOptions): Promise<AgentHandle>;
+}
+
+declare module "cordis" {
+  interface Context {
+    agents: AgentRegistry;
+  }
+
+  interface Events {
+    "agent/created": (agent: Agent) => void;
+    "agent/disposed": (agent: Agent) => void;
+    "agent/status": (agent: Agent, status: AgentStatus) => void;
+    "agent/inbox/inserted": (agent: Agent, input: AgentInput) => void;
+    "agent/inbox/claimed": (
+      agent: Agent,
+      inputs: AgentInput[],
+      turn: number,
+    ) => void;
+    "agent/pre-step": (
+      agent: Agent,
+      inputs: AgentInput[],
+      turn: number,
+      step: number,
+      next: () => Promise<PreStepDecision>,
+    ) => Promise<PreStepDecision>;
+    "agent/request": (
+      agent: Agent,
+      request: NormalizedModelRequest,
+      signal: AbortSignal,
+      next: () => Promise<NormalizedModelRequest>,
+    ) => Promise<NormalizedModelRequest>;
+    "agent/request-error": (
+      agent: Agent,
+      error: unknown,
+      signal: AbortSignal,
+      next: () => Promise<RequestErrorAction>,
+    ) => Promise<RequestErrorAction>;
+    "agent/model-outcome-committed": (
+      agent: Agent,
+      requestId: string,
+      outcome: "completed" | "not-started",
+    ) => Promise<void>;
+    "agent/turn-stopping": (agent: Agent, turn: number) => Promise<void>;
+    "agent/cancel-requested": (
+      agent: Agent,
+      reason: "user" | "shutdown",
+    ) => void;
+    "agent/error": (agent: Agent, error: unknown) => void;
+  }
+}
+
+export class AgentRegistry extends Service {
+  private agents = new Map<string, Agent>();
+  private factory: AgentFactory | undefined;
+
+  constructor(ctx: Context) {
+    super(ctx, "agents");
+  }
+
+  setFactory(factory: AgentFactory): () => void {
+    if (this.factory) throw new Error("an agent factory is already registered");
+    this.factory = factory;
+    return () => {
+      if (this.factory === factory) this.factory = undefined;
+    };
+  }
+
+  create(options: AgentOptions): Promise<AgentHandle> {
+    if (!this.factory) throw new Error("no agent factory is registered");
+    return this.factory.create(options);
+  }
+
+  register(agent: Agent): () => void {
+    if (this.agents.has(agent.id))
+      throw new Error(`agent "${agent.id}" already exists`);
+    this.agents.set(agent.id, agent);
+    this.ctx.emit("agent/created", agent);
+    return () => {
+      if (this.agents.get(agent.id) !== agent) return;
+      this.agents.delete(agent.id);
+      this.ctx.emit("agent/disposed", agent);
+    };
+  }
+
+  get(agentId: string): Agent | undefined {
+    return this.agents.get(agentId);
+  }
+
+  list(): Agent[] {
+    return [...this.agents.values()];
+  }
+}