@volter/supercode-orchestrator 0.4.159 → 0.5.1

package/mcp/verbs.mjs

@@ -22,6 +22,8 @@ import { compactStamp, gateFields, homeZone, nextRunAt, parseCron, payloadError,
 import { applyOperator, hermesJobArgs } from '../operator.mjs';
 import { hermesSchedule, hermesTool } from '../hermes-cli.mjs';
 import { modelError } from '../activation.mjs';
+import { agentRunForSession } from '../agents.mjs';
+import { materializeAgentHome } from '../agent-home.mjs';
 
 /**
  * cron/jobs.py `_normalize_workdir`, transcribed: returns the absolute,
@@ -64,7 +66,9 @@ export function routedProfile(state, key) {
   const profiles = Object.values(state.profiles);
   const owner = profiles.find((p) => p.channels && p.channels[key.platform]) ?? state.profiles.default ?? profiles[0];
   if (!owner) return null;
-  return resolveRoute(owner.routes, key) ?? owner.name;
+  // a route names an agent (G1); its profile is the agent's own or the declared one's
+  const agent = resolveRoute(owner.routes, key) ?? owner.name;
+  return state.agents?.[agent]?.profile ?? (state.profiles[agent] ? agent : owner.name);
 }
 
 const UNIT_MINUTES = { m: 1, min: 1, mins: 1, minute: 1, minutes: 1, h: 60, hr: 60, hour: 60, hours: 60, d: 1440, day: 1440, days: 1440 };
@@ -321,10 +325,15 @@ export async function runVerb(orch, { verb, args = {}, profile: profileName, sur
     case 'memory':
     case 'skills_list':
     case 'skill_view': {
-      // Hermes's own handler against this profile's home: its sessions (the workers' mirrored beside
-      // Hermes's), its memories, its skills; answered in Hermes's words
-      const verbatim = await hermesTool(profile.dir, verb, args, { sessionId: binding?.worker?.session_id ?? null });
-      return { effects, result: { ran: `${verb} in profile ${profile.name}`, verbatim: typeof verbatim === 'string' ? verbatim : JSON.stringify(verbatim) } };
+      const worker=binding?.worker;
+      let home=profile.dir,scope=`profile ${profile.name}`;
+      if(verb==='memory'||verb==='session_search') {
+        const owner=worker&&agentRunForSession(state.root,[`${worker.harness}:${worker.session_id}`,`${worker.harness}:${worker.runtime_id}`]);
+        if(!owner)throw new Error(`${verb} requires the bound session's agent ownership; a profile is not an agent`);
+        home=materializeAgentHome(state.root,owner.org,owner.agent_id,profile);scope=`agent ${owner.agent_id}`;
+      }
+      const verbatim = await hermesTool(home, verb, args, { sessionId: worker?.session_id ?? null });
+      return { effects, result: { ran: `${verb} in ${scope}`, verbatim: typeof verbatim === 'string' ? verbatim : JSON.stringify(verbatim) } };
     }
 
     case 'session_handoff': {
@@ -333,8 +342,21 @@ export async function runVerb(orch, { verb, args = {}, profile: profileName, sur
       const b = surface ? liveBinding(profile, surface) : null;
       if (!b) throw new Error('No live session to hand off.');
       await orch.dispatch(events.operator({ verb: 'session_handoff', profile: profile.name, args: { keyString: surface, to, note: args.note ? String(args.note) : null }, at: now }));
-      if (b.handoff?.state !== 'pending') return { effects, error: `Cannot hand off: ${b.handoff?.error ?? 'unknown reason'}.` };
-      return { effects, result: { ran: `handed off to ${to}; the binding is pending pickup`, session_id: b.worker.session_id } };
+      const record = [...(orch.state.handoffs ?? [])].reverse().find((h) => h.session === `${b.worker.harness}:${b.worker.session_id ?? ''}` && h.at === now);
+      if (record?.state !== 'pending') return { effects, error: `Cannot hand off: ${record?.error ?? 'unknown reason'}.` };
+      return { effects, result: { ran: `handed off to ${to}; the session is pending pickup`, session_id: b.worker.session_id } };
+    }
+
+    case 'conversation_transfer': {
+      const to = args.to ? String(args.to) : '';
+      if (!to) throw new Error('to is required');
+      const b = surface ? liveBinding(profile, surface) : null;
+      if (!b) throw new Error('No live conversation to transfer.');
+      const history = ['full', 'filtered', 'none'].includes(args.history) ? args.history : 'full';
+      await orch.dispatch(events.operator({ verb: 'conversation_transfer', profile: profile.name, args: { keyString: surface, to, reason: String(args.reason ?? ''), history, ...(history === 'filtered' ? { filter: { last: Number(args.last ?? 20) } } : {}) }, at: now }));
+      const record = [...(orch.state.transfers ?? [])].reverse().find((t) => t.at === now && t.to === to);
+      if (record?.state !== 'done') return { effects, error: `Transfer refused: ${record?.error ?? 'unknown reason'}.` };
+      return { effects, result: { ran: `transferred the conversation to ${to}`, conversation: record.conversation } };
     }
 
     default:

package/ontology.d.ts

@@ -31,6 +31,26 @@ export interface Action {
   args: unknown;
 }
 
+/**
+ * One agent this home declares: who answers, and which profile is its template.
+ * A named profile implies its own agent of the same name; a declaration names others (several
+ * agents may share one profile) and the parent each is declared under.
+ */
+export interface AgentDecl {
+  /** Unique among the home's agents; a route, a speaker policy and a binding name it. */
+  name: string;
+  /** The profile it runs as (its layered template). */
+  profile: string;
+  /** A display label, not identity. */
+  label?: string | null;
+  /** The agent it is declared under, if not the home's root. */
+  parent?: string | null;
+  /** A person set on purpose as its sponsor; absent, the sponsor is inherited. */
+  sponsor?: string | null;
+  /** What a source format said about it that the IR has no field for, verbatim. */
+  residue?: Record<string, unknown>;
+}
+
 /** What one artifact reached on the way in or out. */
 export interface ArtifactFidelity {
   /** Path relative to the home the codec read or wrote. */
@@ -65,6 +85,10 @@ export interface Binding {
   key: SurfaceKey;
   /** The profile that owns it (`None` = the home's default). */
   profile?: string | null;
+  /** The conversation it holds a session in (G1/G5); `None` where the source records none. */
+  conversation?: string | null;
+  /** The agent whose session it is; with `conversation`, its key. `None` where the source records none. */
+  agent?: string | null;
   /** The worker session. */
   worker: Worker;
   /**
@@ -89,6 +113,34 @@ export interface Binding {
   residue?: Residue;
 }
 
+/**
+ * A per-action gate on a profile's agents: a start or resume over it is refused, with the reason,
+ * and the refusal is told to the manager and the sponsor. It never pauses or ends anything itself.
+ */
+export interface Budget {
+  /** The window. */
+  period: BudgetPeriod;
+  /** The bound. */
+  limit: BudgetLimit;
+}
+
+/** What a budget bounds. */
+export interface BudgetLimit {
+  /** Total tokens. */
+  tokens?: number | null;
+  /** Total cost. */
+  cost?: Cost | null;
+}
+
+/** A budget's window. */
+export type BudgetPeriod =
+  /** One run. */
+  | 'run'
+  /** A calendar day. */
+  | 'day'
+  /** A calendar month. */
+  | 'month';
+
 /** One platform's configuration. */
 export interface ChannelConfig {
   /** The platform name (`telegram`, `slack`, `api_server`, …). */
@@ -101,6 +153,43 @@ export interface ChannelConfig {
   extra?: Record<string, unknown>;
 }
 
+/** A conversation, a Resource separate from the sessions bound to it (G5, amended by M3). */
+export interface Conversation {
+  /** Its id. */
+  id: string;
+  /** Thread or private. */
+  kind: ConversationKind;
+  /** Where a thread is shown; no profile is part of it. */
+  surface?: SurfaceKey | null;
+  /** People and agents in it. */
+  participants?: Participant[];
+  /** Who receives a line. */
+  speaker?: SpeakerPolicy;
+  /** Where its record lives. */
+  history?: HistoryRef;
+  /** The agent a completed transfer gave the conversation to; an unaddressed line goes to it. */
+  holder?: string | null;
+  /** The agent that took the last line (round robin's position). */
+  last_speaker?: string | null;
+}
+
+/** `thread`: a root and its replies, wherever it is shown; `private`: a harness session's own input. */
+export type ConversationKind =
+  /** A root and its replies (a Room conversation, a chat thread, a mailbox exchange). */
+  | 'thread'
+  /** A harness session's own conversation with its owner; its history is that transcript. */
+  | 'private';
+
+/** A cost, as the provider reported it or a rate table priced it. */
+export interface Cost {
+  /** The amount. */
+  amount: number;
+  /** ISO currency. */
+  currency: string;
+  /** `provider` or `rate_table`. */
+  source?: string | null;
+}
+
 /** A transition taken once a duration has passed in the status (XState's `after`, ASL's `Wait`). */
 export interface Delayed {
   /** How long, in seconds (an expression). */
@@ -152,6 +241,10 @@ export type EndReason =
   | 'new'
   /** Moved to another surface. */
   | 'handoff'
+  /** The conversation was transferred to another agent (G2). */
+  | 'transfer'
+  /** The agent left the conversation. */
+  | 'left'
   /** The worker failed. */
   | 'error';
 
@@ -240,9 +333,43 @@ export interface Handoff {
   error?: string | null;
 }
 
+/** A session moving to another conversation (Hermes `/handoff`, kept by the naming rule). */
+export interface Handoff2 {
+  /** The session (`<harness>:<id>`). */
+  session: string;
+  /** The target conversation. */
+  to: string;
+  /** Who asked. */
+  by: string;
+  /** Its progress. */
+  state: HandoffState;
+  /** Why it failed. */
+  error?: string | null;
+  /** RFC3339. */
+  at: string;
+}
+
+/** A handoff's progress. */
+export type HandoffState =
+  /** Announced on the target, not yet picked up. */
+  | 'pending'
+  /** The session is bound there. */
+  | 'done'
+  /** It could not move. */
+  | 'failed';
+
 /** Extensible identifier for a coding harness. */
 export type HarnessId = string;
 
+/** Where a conversation's record lives. */
+export type HistoryRef =
+  /** The platform's own thread (a chat thread, a Room conversation). */
+  | { kind: 'platform' }
+  /** The mailbox thread. */
+  | { thread: string; kind: 'mailbox' }
+  /** A private conversation's history: its owning session's transcript. */
+  | { session: string; kind: 'transcript' };
+
 /** One scheduled job. */
 export interface Job {
   /** The id (a file-name-safe token). */
@@ -270,6 +397,11 @@ export interface Job {
    * the worker allows), instead of a session of its own; Hermes mirrors it into that transcript.
    */
   attach_to_session?: boolean | null;
+  /**
+   * Which session a fire runs in: `main` (its agent's main session), `current` (the binding's session),
+   * `isolated` (a new one) or `session:<id>` (that one). Absent: the source's own default.
+   */
+  session_target?: string | null;
   /** Remaining-runs counter for `once` jobs. */
   repeat?: Repeat | null;
   /** Whether it fires at all. */
@@ -373,6 +505,16 @@ export interface Orchestration {
   profiles: Record<string, Profile>;
   /** O — how the home's boards are worked (`workflow.yaml` at the root; Hermes's dispatcher when there is none). */
   workflow?: Workflow;
+  /** O — declared agents by name (§2.10); a named profile implies its own agent without one. */
+  agents?: Record<string, AgentDecl>;
+  /** O — conversations by id, separate from the sessions bound to them (G5). */
+  conversations?: Record<string, Conversation>;
+  /** O — transfers between agents, in order (G2). */
+  transfers?: Transfer[];
+  /** O — sessions moved to other conversations, in order (G2). */
+  handoffs?: Handoff2[];
+  /** O — usage per session (`<harness>:<id>`), summed per agent (G3). */
+  usage?: Record<string, SessionUsage>;
 }
 
 /** What is delivered. */
@@ -387,6 +529,25 @@ export interface OutboundContent {
   format?: string | null;
 }
 
+/** A person or an agent in a conversation. */
+export interface Participant {
+  /** An agent's name, or a person as `<platform>:<user id>` (an identity observation). */
+  principal: string;
+  /** To or CC. */
+  role: ParticipantRole;
+  /** RFC3339. */
+  since: string;
+  /** RFC3339, when it left. */
+  until?: string | null;
+}
+
+/** How a participant is addressed on a thread (amendment M3). */
+export type ParticipantRole =
+  /** Addressed: expected to act. */
+  | 'to'
+  /** Copied: receives every reply. */
+  | 'cc';
+
 /** What happens to a worker's permission prompt when no human answers. */
 export type PermissionDefault =
   /** Refuse after the timeout. */
@@ -459,6 +620,8 @@ export interface Profile {
   fires?: Fire[];
   /** H — `delivery_obligations`. */
   obligations?: Obligation[];
+  /** O — per-action gates on this profile's agents (G3); they only narrow down the layers. */
+  budgets?: Budget[];
   /** What the model does not interpret. */
   residue?: ProfileResidue;
 }
@@ -504,8 +667,8 @@ export interface Route {
   name?: string | null;
   /** What it matches. */
   match: RouteMatch;
-  /** The profile that answers. */
-  profile: string;
+  /** The agent that answers (G1); a named profile's own agent bears the profile's name. */
+  agent: string;
   /** Unmodeled fields of the route, verbatim. */
   residue?: Residue;
 }
@@ -581,6 +744,27 @@ export type SecretRef =
   /** A key in the home's own `.env` file. */
   | { dotenv: string };
 
+/** A session's usage, kept on the session and summed upward (session → agent → sponsor → Org). */
+export interface SessionUsage {
+  /** The agent the session belongs to, when it has one. */
+  agent?: string | null;
+  /** The records. */
+  usage?: Usage[];
+}
+
+/** Which bound agents receive a line on a shared surface (G1). */
+export type SpeakerPolicy =
+  /** Mentions pick the agent; `default` takes the rest (a Hermes or OpenClaw surface: one agent). */
+  | { default?: string | null; kind: 'addressed' }
+  /** Every bound agent gets every line. */
+  | { kind: 'all' }
+  /** Agents take lines in this order. */
+  | { order: string[]; kind: 'round_robin' }
+  /** An agent picks the next speaker (an event out and back, never a hidden model call). */
+  | { selector: string; kind: 'selector' }
+  /** The meeting's adapter decides (RH2's floor, the voice pack). */
+  | { kind: 'floor' };
+
 /** One status a card can be in. */
 export interface Status {
   /**
@@ -647,6 +831,48 @@ export type Target =
   /** A named surface, as `hermes send --to` spells one. */
   | { platform: string; chat_id?: string | null; thread_id?: string | null; kind: 'explicit' };
 
+/** One agent handing a conversation to another (OpenAI handoff, AutoGen Swarm, voice `hand_off`). */
+export interface Transfer {
+  /** The conversation. */
+  conversation: string;
+  /** The giving agent. */
+  from: string;
+  /** The receiving agent. */
+  to: string;
+  /** Who did it (the giving agent, or whom the speaker policy allows). */
+  by: string;
+  /** Why. */
+  reason: string;
+  /** What history the receiver is given. */
+  history: TransferHistory;
+  /** For `filtered`: which part (`{"last": N}`). */
+  filter?: unknown;
+  /** Its progress. */
+  state: TransferState;
+  /** RFC3339. */
+  at: string;
+  /** Why it was refused. */
+  error?: string | null;
+}
+
+/** How much of the conversation a transfer's receiver is given. */
+export type TransferHistory =
+  /** All of it (the default). */
+  | 'full'
+  /** What the filter keeps. */
+  | 'filtered'
+  /** None. */
+  | 'none';
+
+/** A transfer's progress. */
+export type TransferState =
+  /** Asked, not yet applied. */
+  | 'pending'
+  /** The receiver holds the conversation. */
+  | 'done'
+  /** The receiver may not take part. */
+  | 'refused';
+
 /** A move from the card's status on an event (or on none: `always`, `after`). */
 export interface Transition {
   /** Source statuses; empty applies from every status. */
@@ -689,6 +915,24 @@ export type Trigger =
   /** The source does not say. */
   | 'unknown';
 
+/** One measured use of a model, from the harness's own records (G3). */
+export interface Usage {
+  /** RFC3339. */
+  at: string;
+  /** The model. */
+  model: string;
+  /** Input tokens. */
+  input_tokens: number;
+  /** Output tokens. */
+  output_tokens: number;
+  /** Cache reads, when measured. */
+  cache_read_tokens?: number | null;
+  /** Cache writes, when measured. */
+  cache_write_tokens?: number | null;
+  /** Its cost, when known. */
+  cost?: Cost | null;
+}
+
 /** A validator: the expression must hold, else the event is refused with the message. */
 export interface Validation {
   /** What must hold. */

package/operator.mjs

@@ -43,6 +43,7 @@ export const OPERATOR_OPS = Object.freeze([
   'profiles.create', 'profiles.delete',
   'sessions.new', 'sessions.reset',
   'access.pair_approve',
+  'agents.fork',
 ]);
 
 /** Where a deleted profile folder is renamed to, relative to the root. */
@@ -387,10 +388,14 @@ async function run(state, profile, op, args, now, send) {
       const code = String(args.code ?? '').trim();
       if (!code) throw new Error('code is required');
       // Hermes's pairing store holds the code; the daemon asks it, and a grant reaches the allowlist
-      await send('pair_approve', { code });
+      await send('pair_approve', { code, principal: args.principal ? String(args.principal) : null });
       return { ran: `asked Hermes's pairing store to approve ${code} for profile ${profile.name}`, code };
     }
 
+    case 'agents.fork':
+      // The live daemon's door performs it (mcp/bridge.mjs): it declares a child and starts its session.
+      throw new Error('agents.fork starts the child agent\'s session; it runs only through a live orchestrator daemon');
+
     default:
       throw new Error(`unknown operator op ${op}`);
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/supercode-orchestrator",
-  "version": "0.4.159",
+  "version": "0.5.1",
   "type": "module",
   "description": "The orchestrator runtime over the Volter Harness ontology: one typed operational model whose folder is its serialization, read and written through the harness orchestration doors (docs/ORCHESTRATOR-IR.md)",
   "exports": {
@@ -27,7 +27,7 @@
     "@volter/supercode-harness-sdk": "^0.3.41",
     "@volter/ztrack": "^2.4.21",
     "yaml": "^2.9.0",
-    "@volter/supercode-teams": "^0.2.145"
+    "@volter/teams": "0.2.0"
   },
   "devDependencies": {
     "@chat-adapter/state-memory": "4.39.0",