@rowan-agent/agent 0.5.1 → 0.5.3

package/README.md

@@ -42,14 +42,51 @@ The `Agent` class is the public facade. It drives the entire execution loop —
 ```ts
 class Agent {
   constructor(options: AgentOptions);
-  run(options?: RunOptions): Promise<AgentRunResult>;
+  run(options?: RunOptions): Promise<RunResult>;
+
+  // User input / conversation continuation
+  appendUserMessage(input: string): void;
+  appendMessage(message: AgentMessage): void;
+  appendMessages(messages: AgentMessage[]): void;
+  runWithUserInput(input: string, options?: RunOptions): Promise<RunResult>;
+  runWithMessage(message: AgentMessage, options?: RunOptions): Promise<RunResult>;
+
+  // Context and transcript
+  getContext(): AgentContext;
+  setContext(context: AgentContext): void;
+  updateContext(updater: (context: AgentContext) => AgentContext): void;
+  forkContext(overrides?: Partial<AgentContext>): AgentContext;
+  getMessages(): AgentMessage[];
+  setMessages(messages: AgentMessage[]): void;
+  clearMessages(): void;
+  getTranscript(): AgentMessage[];
+  replaceTranscript(messages: AgentMessage[]): void;
+
+  // Config access and shortcuts
+  getConfig(): AgentOptions;
+  setConfig(config: AgentOptions): void;
+  updateConfig(updater: (config: AgentOptions) => AgentOptions): void;
+  setSessionId(sessionId: string): void;
+  getSessionId(): string | undefined;
+  setModel(model: LlmModelRef): void;
+  setTools(tools: Tool[]): void;
+  setSkills(skills: Skill[]): void;
+  setPhases(phases: PhaseRegistry): void;
+  setCwd(cwd: string): void;
+  setStream(stream: StreamFn): void;
+  getModel(): LlmModelRef;
+  getTools(): Tool[];
+  getSkills(): Skill[];
+  getPhases(): PhaseRegistry | undefined;
+  getCwd(): string | undefined;
+
   abort(): void;
   subscribe(listener: AgentEventListener): () => void;
-  skill(name: string): Promise<void>;
+  skill(name: string, additionalInstructions?: string): string;
   phase(name: string): Promise<string>;
   waitForIdle(): Promise<void>;
   flushEvents(): Promise<void>;
-  readonly status: AgentStatus;
+  readonly state: AgentStatus;
 
   // Resource loading — replaces standalone loadSkills/loadPhases/loadExtensions
   static loadSkills(targetPath: string): Promise<Skill[]>;
@@ -65,6 +102,7 @@ type AgentOptions = {
   context: AgentContext;
   model: LlmModelRef;
   stream: StreamFn;
+  cwd?: string;
   extensions?: LoadedExtension[];
   sessionId?: string;
   maxAttempts?: number;
@@ -78,18 +116,57 @@ type AgentOptions = {
 };
 ```
 
-### AgentRunResult
+### RunResult
 
 ```ts
-type AgentRunResult = {
-  status: AgentStatus;
-  outcome?: Outcome;
-  metrics?: LoopMetrics;
-  messages: AgentMessage[];
+type RunResult = {
   sessionId: string;
+  messages: AgentMessage[];
+  outcome: Outcome;
+  metrics: LoopMetrics;
 };
 ```
 
+### Conversation Continuation
+
+For multi-turn use, append input to the agent's current transcript and run with the updated context. `runWithUserInput()` is the main convenience API; the lower-level append methods are useful when a UI or session layer controls message creation.
+
+```ts
+const first = await agent.runWithUserInput("summarize this repository");
+
+agent.appendUserMessage("now focus on the CLI package");
+const second = await agent.run();
+
+await agent.runWithMessage(createMessage("user", "what changed since last turn?"));
+```
+
+Transcript helpers return snapshots, so callers can inspect or edit history without accidentally mutating the agent until they call a setter.
+
+```ts
+const messages = agent.getMessages();
+agent.replaceTranscript(messages.slice(-6));
+agent.clearMessages();
+```
+
+### Updating Config
+
+`AgentOptions` can be replaced wholesale with `setConfig()`, or updated through focused shortcuts for common orchestration flows.
+
+```ts
+agent.setSessionId("ses_known");
+agent.setModel({ provider: "openai", id: "gpt-4.1" });
+agent.setTools(createCoreTools({ root: process.cwd() }));
+agent.setSkills(await Agent.loadSkills("./.rowan/skills"));
+agent.setPhases(await Agent.loadPhases("./.rowan/phases"));
+agent.setCwd(process.cwd());
+agent.setStream(createDispatchStream());
+
+agent.updateContext((context) => ({
+  ...context,
+  systemPrompt: `${context.systemPrompt}\n\nPrefer concise answers.`,
+}));
+```
+
 ## AgentContext
 
 The context snapshot that defines what the agent can see and do — the system prompt sets the role, messages form the conversation history, and tools/skills define the capability boundary.

package/dist/index.d.ts

@@ -1376,6 +1376,36 @@ declare class Agent {
     static loadExtensions(targetPath: string): Promise<LoadExtensionsResult>;
     constructor(options: AgentOptions);
     subscribe(listener: AgentEventListener): Unsubscribe;
+    appendUserMessage(input: string): void;
+    appendMessage(message: AgentMessage): void;
+    appendMessages(messages: AgentMessage[]): void;
+    runWithUserInput(input: string, options?: RunOptions): Promise<RunResult>;
+    runWithMessage(message: AgentMessage, options?: RunOptions): Promise<RunResult>;
+    getContext(): AgentContext;
+    setContext(context: AgentContext): void;
+    updateContext(updater: (context: AgentContext) => AgentContext): void;
+    forkContext(overrides?: Partial<AgentContext>): AgentContext;
+    getMessages(): AgentMessage[];
+    setMessages(messages: AgentMessage[]): void;
+    clearMessages(): void;
+    getTranscript(): AgentMessage[];
+    replaceTranscript(messages: AgentMessage[]): void;
+    getConfig(): AgentOptions;
+    setConfig(config: AgentOptions): void;
+    updateConfig(updater: (config: AgentOptions) => AgentOptions): void;
+    setSessionId(sessionId: string): void;
+    getSessionId(): string | undefined;
+    setModel(model: LlmModelRef): void;
+    setTools(tools: Tool[]): void;
+    setSkills(skills: Skill$1[]): void;
+    setPhases(phases: PhaseRegistry): void;
+    setCwd(cwd: string): void;
+    setStream(stream: StreamFn): void;
+    getModel(): LlmModelRef;
+    getTools(): Tool[];
+    getSkills(): Skill$1[];
+    getPhases(): PhaseRegistry | undefined;
+    getCwd(): string | undefined;
     private emitToListeners;
     flushEvents(): Promise<void>;
     private processEvents;
@@ -1434,6 +1464,7 @@ declare class Agent {
     waitForIdle(): Promise<void>;
     private resolveRunConfig;
     private createContextSnapshot;
+    private cloneOptions;
 }
 
 declare function createId(prefix: string): string;

package/dist/index.js

@@ -94,6 +94,9 @@ var createOutcome = {
       id: createId("out"),
       message
     };
+    if (output.payload !== void 0) {
+      outcome.payload = output.payload;
+    }
     if (toolResults.length > 0) {
       outcome.toolResults = toolResults;
     }
@@ -3426,14 +3429,14 @@ var Agent = class {
     return loadExtensionsFromPath(targetPath);
   }
   constructor(options) {
-    const context = cloneAgentContext(options.context);
+    const context = prepareAgentContext(options.context);
     this.options = {
       ...options,
       context
     };
     this.state = {
       ...this.options.sessionId ? { sessionId: this.options.sessionId } : {},
-      context: cloneAgentContext(context),
+      context: prepareAgentContext(context),
       model: this.options.model,
       tools: this.options.context.tools ?? [],
       isRunning: false
@@ -3445,6 +3448,142 @@ var Agent = class {
       this.listeners.delete(listener);
     };
   }
+  appendUserMessage(input) {
+    this.appendMessage(createMessage("user", input));
+  }
+  appendMessage(message) {
+    this.appendMessages([message]);
+  }
+  appendMessages(messages) {
+    this.setMessages([...this.options.context.messages, ...snapshotMessages(messages)]);
+  }
+  runWithUserInput(input, options) {
+    this.appendUserMessage(input);
+    return this.run(options);
+  }
+  runWithMessage(message, options) {
+    this.appendMessage(message);
+    return this.run(options);
+  }
+  getContext() {
+    return prepareAgentContext(this.options.context);
+  }
+  setContext(context) {
+    const nextContext = prepareAgentContext(context);
+    this.options = {
+      ...this.options,
+      context: nextContext
+    };
+    this.state.context = prepareAgentContext(nextContext, this.extensionRunner);
+    this.state.tools = this.state.context.tools ?? [];
+  }
+  updateContext(updater) {
+    this.setContext(updater(this.getContext()));
+  }
+  forkContext(overrides = {}) {
+    return prepareAgentContext({
+      ...this.getContext(),
+      ...overrides
+    });
+  }
+  getMessages() {
+    return snapshotMessages(this.options.context.messages);
+  }
+  setMessages(messages) {
+    this.setContext({
+      ...this.options.context,
+      messages: snapshotMessages(messages)
+    });
+  }
+  clearMessages() {
+    this.setMessages([]);
+  }
+  getTranscript() {
+    return this.getMessages();
+  }
+  replaceTranscript(messages) {
+    this.setMessages(messages);
+  }
+  getConfig() {
+    return this.cloneOptions(this.options);
+  }
+  setConfig(config) {
+    const context = prepareAgentContext(config.context);
+    this.options = {
+      ...config,
+      context,
+      ...config.extensions ? { extensions: config.extensions.slice() } : {}
+    };
+    this.state.sessionId = config.sessionId;
+    this.state.context = prepareAgentContext(context, this.extensionRunner);
+    this.state.model = config.model;
+    this.state.tools = this.state.context.tools ?? [];
+  }
+  updateConfig(updater) {
+    this.setConfig(updater(this.getConfig()));
+  }
+  setSessionId(sessionId) {
+    this.options = {
+      ...this.options,
+      sessionId
+    };
+    this.state.sessionId = sessionId;
+  }
+  getSessionId() {
+    return this.state.sessionId;
+  }
+  setModel(model) {
+    this.options = {
+      ...this.options,
+      model
+    };
+    this.state.model = model;
+  }
+  setTools(tools) {
+    this.setContext({
+      ...this.options.context,
+      tools: tools.slice()
+    });
+  }
+  setSkills(skills) {
+    this.setContext({
+      ...this.options.context,
+      skills: skills.slice()
+    });
+  }
+  setPhases(phases) {
+    this.setContext({
+      ...this.options.context,
+      phases: clonePhaseRegistry(phases)
+    });
+  }
+  setCwd(cwd) {
+    this.options = {
+      ...this.options,
+      cwd
+    };
+  }
+  setStream(stream) {
+    this.options = {
+      ...this.options,
+      stream
+    };
+  }
+  getModel() {
+    return this.state.model;
+  }
+  getTools() {
+    return this.state.context.tools.slice();
+  }
+  getSkills() {
+    return this.state.context.skills.slice();
+  }
+  getPhases() {
+    return this.state.context.phases ? clonePhaseRegistry(this.state.context.phases) : void 0;
+  }
+  getCwd() {
+    return this.options.cwd;
+  }
   emitToListeners(event) {
     for (const listener of this.listeners) {
       try {
@@ -3590,7 +3729,7 @@ var Agent = class {
     const resolved = this.resolveRunConfig(config);
     const extensions = resolved.extensions ?? [];
     await this.loadExtensions(extensions, resolved.cwd);
-    const runContext = cloneAgentContext(resolved.context, this.extensionRunner);
+    const runContext = prepareAgentContext(resolved.context, this.extensionRunner);
     const sessionId = resolved.sessionId ?? this.state.sessionId;
     this.options = resolved;
     if (sessionId) {
@@ -3641,11 +3780,11 @@ var Agent = class {
         onModelTranscript: resolved.onModelTranscript
       });
       const nextContext = {
-        ...cloneAgentContext(resolved.context),
+        ...prepareAgentContext(resolved.context),
         messages: snapshotMessages(result.messages)
       };
       this.state.sessionId = result.sessionId;
-      this.state.context = cloneAgentContext(nextContext, this.extensionRunner);
+      this.state.context = prepareAgentContext(nextContext, this.extensionRunner);
       this.state.currentResult = result;
       this.options = {
         ...resolved,
@@ -3689,7 +3828,7 @@ ${additionalInstructions}` : content;
    */
   async phase(name) {
     await this.loadExtensions(this.options.extensions ?? [], this.options.cwd);
-    const registry = cloneAgentContext(this.options.context, this.extensionRunner).phases?.phases;
+    const registry = prepareAgentContext(this.options.context, this.extensionRunner).phases?.phases;
     const phase = registry?.get(name) ?? [...registry?.values() ?? []].find((candidate) => candidate.name === name);
     return phase ? readPhaseContent(phase) : "";
   }
@@ -3705,7 +3844,7 @@ ${additionalInstructions}` : content;
       ...this.options,
       ...config
     };
-    const context = cloneAgentContext(config?.context ?? this.createContextSnapshot());
+    const context = prepareAgentContext(config?.context ?? this.createContextSnapshot());
     return {
       ...merged,
       context,
@@ -3713,10 +3852,23 @@ ${additionalInstructions}` : content;
     };
   }
   createContextSnapshot() {
-    return cloneAgentContext(this.options.context);
+    return prepareAgentContext(this.options.context);
+  }
+  cloneOptions(options) {
+    return {
+      ...options,
+      context: prepareAgentContext(options.context),
+      ...options.extensions ? { extensions: options.extensions.slice() } : {}
+    };
   }
 };
-function cloneAgentContext(context, extensionRunner) {
+function clonePhaseRegistry(registry) {
+  return {
+    phases: new Map(registry.phases),
+    entryPhaseId: registry.entryPhaseId
+  };
+}
+function prepareAgentContext(context, extensionRunner) {
   const phases = /* @__PURE__ */ new Map();
   phases.set(DEFAULT_PHASE_ID, createDefaultPhase());
   for (const [id, phase] of context.phases?.phases ?? []) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rowan-agent/agent",
-  "version": "0.5.1",
+  "version": "0.5.3",
   "license": "MIT",
   "repository": {
     "type": "git",