macro-agent 0.1.1 → 0.1.3

package/src/steering/index.ts

@@ -1,25 +0,0 @@
-/**
- * Steering Module
- *
- * Context injection and in-flight steering for agents.
- *
- * @module steering
- * @see s-9rld In-Flight Steering spec
- */
-
-// Types
-export type {
-  InjectionSource,
-  InjectionOptions,
-  InjectionMethod,
-  InjectionResult,
-  InjectableSession,
-  InjectionDeps,
-} from "./types.js";
-
-// Core functions
-export {
-  injectContext,
-  createInjector,
-  formatInjectedContent,
-} from "./inject.js";

package/src/steering/inject.ts

@@ -1,262 +0,0 @@
-/**
- * Context Injection
- *
- * Implements the core injectContext() function with full fallback chain:
- * 1. Try session.inject() if supported
- * 2. Fall back to session.interruptWith() if allowed
- * 3. Fall back to high-priority message
- *
- * @module steering/inject
- * @see s-9rld In-Flight Steering spec section 3.1
- */
-
-import type { AgentId } from "../store/types/index.js";
-import type {
-  InjectionOptions,
-  InjectionResult,
-  InjectionDeps,
-  InjectableSession,
-} from "./types.js";
-
-// =============================================================================
-// Default Options
-// =============================================================================
-
-const DEFAULT_OPTIONS: Required<Omit<InjectionOptions, "source" | "reason">> = {
-  allowInterrupt: true,
-  urgent: false,
-};
-
-// =============================================================================
-// Context Formatting
-// =============================================================================
-
-/**
- * Format injected content with metadata for context.
- */
-export function formatInjectedContent(
-  content: string,
-  options: InjectionOptions
-): string {
-  const lines: string[] = [];
-
-  // Add header based on source
-  if (options.source?.type === "human") {
-    lines.push("[Context Injection from User]");
-  } else if (options.source?.type === "agent") {
-    lines.push(`[Context Injection from Agent: ${options.source.agentId}]`);
-  } else {
-    lines.push("[Context Injection]");
-  }
-
-  // Add reason if provided
-  if (options.reason) {
-    lines.push(`Reason: ${options.reason}`);
-  }
-
-  // Add the actual content
-  lines.push("");
-  lines.push(content);
-
-  return lines.join("\n");
-}
-
-// =============================================================================
-// Core Injection Logic
-// =============================================================================
-
-/**
- * Attempt to inject via session.inject().
- * Returns null if not supported or failed.
- */
-async function tryInject(
-  session: InjectableSession,
-  content: string
-): Promise<InjectionResult | null> {
-  // Check if inject is supported
-  if (!session.supportsInject()) {
-    // Try to verify with actual probe
-    const supported = await session.checkInjectSupport();
-    if (!supported) {
-      return null;
-    }
-  }
-
-  try {
-    const result = await session.inject(content);
-    if (result.success) {
-      return {
-        success: true,
-        method: "inject",
-        note: "Queued for next turn",
-      };
-    }
-    // Inject returned failure
-    return null;
-  } catch {
-    // Inject threw an error
-    return null;
-  }
-}
-
-/**
- * Attempt to inject via session.interruptWith().
- * This cancels current work and restarts with the new content.
- */
-async function tryInterrupt(
-  session: InjectableSession,
-  content: string
-): Promise<InjectionResult | null> {
-  try {
-    // Prepend context to explain the interruption
-    const interruptContent = `[PRIORITY UPDATE - Previous work interrupted]\n\n${content}\n\nPlease incorporate this context and continue.`;
-
-    // Drive the async iterator to completion
-    // We don't need to process the updates, just ensure the interrupt happens
-    const iterable = session.interruptWith(interruptContent);
-    const iterator = iterable[Symbol.asyncIterator]();
-
-    // Consume the first update to ensure the interrupt is processed
-    // Then let it run in the background
-    const firstUpdate = await iterator.next();
-
-    if (firstUpdate.done === false) {
-      // Interrupt started successfully, let it continue in background
-      // We don't await all updates to avoid blocking
-      (async () => {
-        try {
-          for await (const _ of iterable) {
-            // Just drive the iterator to completion
-          }
-        } catch {
-          // Ignore errors during background iteration
-        }
-      })();
-    }
-
-    return {
-      success: true,
-      method: "interrupt",
-      note: "Cancelled current work and restarted with context",
-    };
-  } catch (error) {
-    return null;
-  }
-}
-
-/**
- * Inject context into an agent's session.
- *
- * Uses a fallback chain:
- * 1. If urgent, prefer interrupt for immediate effect
- * 2. Try session.inject() if supported (queues for next turn)
- * 3. Fall back to session.interruptWith() if allowInterrupt is true
- * 4. Fall back to sending a high-priority message
- *
- * @param deps - Dependencies for session access and messaging
- * @param targetAgentId - The agent to inject context into
- * @param content - The context to inject
- * @param options - Injection options
- * @returns Result of the injection attempt
- */
-export async function injectContext(
-  deps: InjectionDeps,
-  targetAgentId: AgentId,
-  content: string,
-  options: InjectionOptions = {}
-): Promise<InjectionResult> {
-  const opts = { ...DEFAULT_OPTIONS, ...options };
-  const formattedContent = formatInjectedContent(content, options);
-
-  // Get the target agent's session
-  const session = deps.getSession(targetAgentId);
-
-  // If no session, fall back to message
-  if (!session) {
-    return await sendFallbackMessage(
-      deps,
-      targetAgentId,
-      formattedContent,
-      options.source,
-      "Agent has no active session"
-    );
-  }
-
-  // Check if agent is currently prompting
-  const isPrompting = deps.isPrompting(targetAgentId);
-
-  // If urgent, prefer interrupt for immediate effect
-  if (opts.urgent && isPrompting) {
-    const result = await tryInterrupt(session, formattedContent);
-    if (result) {
-      return result;
-    }
-    // If interrupt failed, try inject as fallback
-  }
-
-  // Try inject first (if not urgent or interrupt failed)
-  const injectResult = await tryInject(session, formattedContent);
-  if (injectResult) {
-    return injectResult;
-  }
-
-  // Try interrupt as fallback (if allowed and agent is prompting)
-  if (opts.allowInterrupt && isPrompting) {
-    const interruptResult = await tryInterrupt(session, formattedContent);
-    if (interruptResult) {
-      return interruptResult;
-    }
-  }
-
-  // Fall back to high-priority message
-  return await sendFallbackMessage(
-    deps,
-    targetAgentId,
-    formattedContent,
-    options.source,
-    "Inject and interrupt not available"
-  );
-}
-
-/**
- * Send a high-priority message as fallback.
- */
-async function sendFallbackMessage(
-  deps: InjectionDeps,
-  targetAgentId: AgentId,
-  content: string,
-  source: InjectionOptions["source"],
-  reason: string
-): Promise<InjectionResult> {
-  try {
-    const fromAgentId = source?.type === "agent" ? source.agentId : undefined;
-    await deps.sendMessage(fromAgentId, targetAgentId, content, "high");
-
-    return {
-      success: true,
-      method: "message",
-      note: `Sent as high-priority message (${reason})`,
-    };
-  } catch (error) {
-    return {
-      success: false,
-      error: `Failed to send message: ${error instanceof Error ? error.message : String(error)}`,
-    };
-  }
-}
-
-// =============================================================================
-// Convenience Wrappers
-// =============================================================================
-
-/**
- * Create an injection function bound to specific dependencies.
- * Useful for creating a pre-configured injector.
- */
-export function createInjector(deps: InjectionDeps) {
-  return (
-    targetAgentId: AgentId,
-    content: string,
-    options?: InjectionOptions
-  ) => injectContext(deps, targetAgentId, content, options);
-}

package/src/steering/types.ts

@@ -1,143 +0,0 @@
-/**
- * Context Injection Types
- *
- * Types for the context injection system that enables steering agents
- * mid-execution via inject, interrupt, or message fallback.
- *
- * @module steering/types
- * @see s-9rld In-Flight Steering spec section 3.1
- */
-
-import type { AgentId } from "../store/types/index.js";
-
-// =============================================================================
-// Injection Source
-// =============================================================================
-
-/**
- * Source of a context injection for audit tracking
- */
-export type InjectionSource =
-  | { type: "human" }
-  | { type: "agent"; agentId: AgentId };
-
-// =============================================================================
-// Injection Options
-// =============================================================================
-
-/**
- * Options for context injection
- */
-export interface InjectionOptions {
-  /**
-   * Allow falling back to interruptWith() if inject() fails.
-   * Warning: This will cancel the agent's current work.
-   * @default true
-   */
-  allowInterrupt?: boolean;
-
-  /**
-   * Force interrupt even if inject is available.
-   * Use for urgent redirects that need immediate effect.
-   * @default false
-   */
-  urgent?: boolean;
-
-  /**
-   * Source of the injection for audit logging.
-   */
-  source?: InjectionSource;
-
-  /**
-   * Optional reason for the injection (for audit logs).
-   */
-  reason?: string;
-}
-
-// =============================================================================
-// Injection Result
-// =============================================================================
-
-/**
- * Method used to deliver the context
- */
-export type InjectionMethod =
-  | "inject" // Used session.inject() - queued for next turn
-  | "interrupt" // Used session.interruptWith() - cancelled and restarted
-  | "message" // Sent as high-priority message
-  | "queued"; // Queued for later (agent not available)
-
-/**
- * Result of a context injection attempt
- */
-export interface InjectionResult {
-  /** Whether the injection was successful */
-  success: boolean;
-
-  /** Method used to deliver the context (if successful) */
-  method?: InjectionMethod;
-
-  /** Error message (if not successful) */
-  error?: string;
-
-  /** Additional notes about the injection */
-  note?: string;
-}
-
-// =============================================================================
-// Session Injection Interface
-// =============================================================================
-
-/**
- * Minimal session interface needed for injection.
- * Matches acp-factory's Session type.
- */
-export interface InjectableSession {
-  /** Inject content to be queued for next turn */
-  inject(
-    content: string,
-    options?: { throwOnUnsupported?: boolean }
-  ): Promise<{ success: boolean; error?: string }>;
-
-  /** Check if inject is supported (cached check) */
-  supportsInject(): boolean;
-
-  /** Check if inject is supported (probes the agent) */
-  checkInjectSupport(): Promise<boolean>;
-
-  /** Interrupt current work and restart with new content */
-  interruptWith(
-    content: string
-  ): AsyncIterable<unknown>;
-}
-
-// =============================================================================
-// Injection Handler Dependencies
-// =============================================================================
-
-/**
- * Dependencies needed by the injection handler
- */
-export interface InjectionDeps {
-  /**
-   * Get a session for an agent.
-   * Returns null if agent has no active session.
-   */
-  getSession(agentId: AgentId): InjectableSession | null;
-
-  /**
-   * Check if an agent is currently processing a prompt.
-   */
-  isPrompting(agentId: AgentId): boolean;
-
-  /**
-   * Send a high-priority message to an agent.
-   * Used as fallback when inject/interrupt are not available.
-   */
-  sendMessage(
-    fromAgentId: AgentId | undefined,
-    toAgentId: AgentId,
-    content: string,
-    priority: "high"
-  ): Promise<void>;
-}

package/src/store/README.md

@@ -1,134 +0,0 @@
-# Store Module
-
-Event-sourced persistence layer for macro-agent. All state changes flow through the EventStore as append-only events.
-
-## Architecture
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│                        EventStore                            │
-│                                                              │
-│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐  │
-│  │   Agents    │  │    Tasks    │  │      Messages       │  │
-│  │  lifecycle  │  │  lifecycle  │  │  routing & history  │  │
-│  └─────────────┘  └─────────────┘  └─────────────────────┘  │
-│         │                │                   │               │
-│         └────────────────┼───────────────────┘               │
-│                          ▼                                   │
-│              ┌─────────────────────┐                         │
-│              │   Backend (SQLite   │                         │
-│              │    or Memory)       │                         │
-│              └─────────────────────┘                         │
-└─────────────────────────────────────────────────────────────┘
-```
-
-## Components
-
-### EventStore (`event-store.ts`)
-
-Central interface for all state operations:
-
-**Agent Operations:**
-- `spawnAgent()` - Create new agent
-- `updateAgentState()` - Change agent state
-- `terminateAgent()` - End agent lifecycle
-- `listAgents()`, `getAgent()` - Query agents
-
-**Task Operations:**
-- `createTask()` - Create new task
-- `assignTask()` - Assign to agent
-- `completeTask()`, `failTask()` - End task
-- `listTasks()`, `getTask()` - Query tasks
-
-**Event Operations:**
-- `emit()` - Append event
-- `getEvents()` - Query events
-- `subscribe()` - Real-time subscriptions
-
-### Types (`types/`)
-
-Type definitions organized by domain:
-
-- `agents.ts` - Agent state, lifecycle
-- `tasks.ts` - Task state, assignment
-- `events.ts` - Event types, payloads
-- `primitives.ts` - Branded ID types (AgentId, TaskId, etc.)
-
-### Backends (`backends/`)
-
-Pluggable storage backends:
-
-- `sqlite-backend.ts` - Persistent SQLite storage
-- `memory-backend.ts` - In-memory (testing)
-
-## Event Types
-
-All state changes are events:
-
-```typescript
-type EventType =
-  | "agent_spawned"
-  | "agent_started"
-  | "agent_terminated"
-  | "task_created"
-  | "task_assigned"
-  | "task_completed"
-  | "message"
-  | "status";
-```
-
-## Usage
-
-```typescript
-import { createEventStore } from "./store/event-store.js";
-import { createSQLiteBackend } from "./store/backends/sqlite-backend.js";
-
-const backend = createSQLiteBackend("./data/events.db");
-const store = createEventStore({ backend });
-
-// Spawn an agent
-const agent = store.spawnAgent({
-  role: "worker",
-  parent_id: coordinatorId,
-});
-
-// Emit an event
-const event = store.emit({
-  type: "message",
-  source: { agent_id: senderId },
-  target: { agent_id: recipientId },
-  payload: { content: "Hello" },
-});
-
-// Subscribe to events
-store.subscribe(agentId, { type: "topic", target: "updates" });
-```
-
-## Subscriptions
-
-Agents can subscribe to:
-
-- **Topic** - Named channels (e.g., "updates", "errors")
-- **Agent** - Direct messages from specific agent
-- **Task** - Events related to a task
-- **Lineage** - Events from descendants
-
-```typescript
-// Subscribe to topic
-store.subscribe(agentId, { type: "topic", target: "system-events" });
-
-// Get subscribers
-const subscribers = store.getSubscribers({ type: "topic", target: "updates" });
-```
-
-## ID Types
-
-The store uses branded types for type safety:
-
-```typescript
-type AgentId = string & { readonly __brand: "AgentId" };
-type TaskId = string & { readonly __brand: "TaskId" };
-type EventId = string & { readonly __brand: "EventId" };
-```
-
-Note: Internal types use `agent_id` (snake_case), while MAP types use `agent`. See CLAUDE.md for naming conventions.