refactor(core): RFC-005 Phase 1 — ThreadContext, AgentFn, Role signature (closes #268)

packages/core/src/index.ts

@@ -20,6 +20,7 @@ export type {
   Role,
   RoleMeta,
   StartStep,
+  ThreadContext,
   WorkflowContext,
   AgentFn,
   RoleStep,

packages/core/src/workflow.ts

@@ -21,39 +21,41 @@ export type WorkflowMessage = {
 /** The typed output of a Role execution. */
 export type RoleResult<Meta> = { content: string; meta: Meta };
 
-/**
- * A Role is a pure async function: receives the engine start frame plus prior
- * role messages only (the start frame is not included in `messages`).
- * Returns typed content + meta. Implementation can be an agent, LLM call,
- * script, HTTP request, etc.
- */
-export type Role<Meta> = (
-  start: StartStep,
-  messages: WorkflowMessage[],
-) => Promise<RoleResult<Meta>>;
-
 /** Maps role names to their meta types — the single generic that drives all inference. */
 export type RoleMeta = Record<string, Record<string, unknown>>;
 
-/** Engine start frame: prompt, max rounds cap, dry-run flag, and timestamps for the thread. */
+/** Engine start frame: initial prompt, max rounds cap, and thread identity. */
 export type StartStep = {
   role: START;
   content: string;
   /** Thread identity (same as workflow `runId`); for role prompts and CLI `nerve thread` context. */
-  meta: { maxRounds: number; dryRun: boolean; threadId: string };
+  meta: { maxRounds: number; threadId: string };
   timestamp: number;
 };
 
-/** Thread context passed to agent adapters (RFC-003): conversation frame, repo root, cancellation. */
-export type WorkflowContext = {
+/**
+ * Thread-scoped context for roles, moderator, and agent adapters (RFC-005).
+ * `workdir` and `signal` are adapter/engine config — not part of this shape.
+ */
+export type ThreadContext<M extends RoleMeta = RoleMeta> = {
+  threadId: string;
   start: StartStep;
-  messages: WorkflowMessage[];
-  workdir: string;
-  signal: AbortSignal;
+  steps: RoleStep<M>[];
 };
 
+/**
+ * @deprecated Use {@link ThreadContext}.
+ */
+export type WorkflowContext = ThreadContext;
+
+/**
+ * A Role receives the full thread context (start frame + prior role steps) and returns
+ * typed content + meta. Implementation can be an agent, LLM call, script, HTTP request, etc.
+ */
+export type Role<Meta> = (ctx: ThreadContext) => Promise<RoleResult<Meta>>;
+
 /** Unified agent invocation — raw string output; structured meta uses the extract layer. */
-export type AgentFn = (prompt: string, context: WorkflowContext) => Promise<string>;
+export type AgentFn = (ctx: ThreadContext, systemPrompt: string) => Promise<string>;
 
 /** A discriminated union of role steps after each execution, aligned with `StartStep` shape. */
 export type RoleStep<M extends RoleMeta> = {
@@ -61,23 +63,17 @@ export type RoleStep<M extends RoleMeta> = {
 }[keyof M & string];
 
 /**
- * Moderator input: the complete workflow history.
- * Contains the start frame and all role steps so far.
- * On initial call, `steps` is empty — moderator can check `steps.length === 0`.
- * Round count is `steps.length`; maxRounds is in `start.meta.maxRounds`.
+ * @deprecated Use {@link ThreadContext}.
  */
-export type ModeratorContext<M extends RoleMeta> = {
-  start: StartStep;
-  steps: RoleStep<M>[];
-};
+export type ModeratorContext<M extends RoleMeta> = ThreadContext<M>;
 
 /**
- * The moderator — a pure routing function. Receives the full workflow context
- * (start frame + all prior steps). Returns the next role name or END.
+ * The moderator — a pure routing function. Receives the full thread context
+ * (start frame + all prior steps). On initial call, `steps` is empty.
+ * Round count is `steps.length`; maxRounds is in `start.meta.maxRounds`.
+ * Returns the next role name or END.
  */
-export type Moderator<M extends RoleMeta> = (
-  context: ModeratorContext<M>,
-) => (keyof M & string) | END;
+export type Moderator<M extends RoleMeta> = (ctx: ThreadContext<M>) => (keyof M & string) | END;
 
 /** The complete definition of a workflow, as authored by users. */
 export type WorkflowDefinition<M extends RoleMeta> = {