@stoneforge/smithy 0.1.0

package/LICENSE

@@ -0,0 +1,13 @@
+Copyright 2026 Adam King
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/README.md

@@ -0,0 +1,114 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/stoneforge-ai/stoneforge/master/brand/logo.svg" alt="Stoneforge" width="120" height="120">
+</p>
+
+# @stoneforge/smithy
+
+Multi-agent orchestration for Stoneforge — directors, workers, and stewards with provider-agnostic session management.
+
+[![npm](https://img.shields.io/npm/v/@stoneforge/smithy)](https://www.npmjs.com/package/@stoneforge/smithy)
+[![license](https://img.shields.io/npm/l/@stoneforge/smithy)](https://github.com/stoneforge-ai/stoneforge/blob/main/LICENSE)
+[![node](https://img.shields.io/node/v/@stoneforge/smithy)](https://nodejs.org)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org)
+
+## Overview
+
+`@stoneforge/smithy` adds AI agent orchestration on top of `@stoneforge/quarry`. It defines three agent roles (director, worker, steward), manages their sessions across multiple providers, dispatches tasks automatically, and isolates work in Git worktrees. Agents communicate through Stoneforge channels and can be monitored via health checks.
+
+## Installation
+
+```bash
+npm install @stoneforge/smithy
+```
+
+The default Claude provider is included. For additional providers, install the corresponding optional dependency:
+
+```bash
+# OpenCode provider
+npm install @opencode-ai/sdk
+```
+
+## Quick Start
+
+```typescript
+import { createOrchestratorAPI } from '@stoneforge/smithy';
+
+const orch = await createOrchestratorAPI({ rootDir: '.stoneforge' });
+
+// Register a director agent
+await orch.registerAgent({
+  role: 'director',
+  name: 'lead',
+  provider: 'claude',
+});
+
+// Register an ephemeral worker
+await orch.registerAgent({
+  role: 'worker',
+  name: 'dev-1',
+  mode: 'ephemeral',
+  provider: 'claude',
+});
+
+// Assign a task — dispatched automatically to an available worker
+await orch.assignTask(taskId, { priority: 'high' });
+```
+
+## Agent Roles
+
+| Role | Session | Description |
+|------|---------|-------------|
+| **Director** | Persistent | Creates tasks and plans, sets priorities, coordinates workers |
+| **Worker (ephemeral)** | Task-scoped | Executes one task in an isolated Git worktree, exits on completion |
+| **Worker (persistent)** | Interactive | Long-lived session for real-time collaboration with a human |
+| **Steward** | Workflow-scoped | Maintenance tasks — merge review, health monitoring, documentation, cleanup |
+
+## Providers
+
+| Provider | Package | Notes |
+|----------|---------|-------|
+| `claude` | `@anthropic-ai/claude-agent-sdk` | Default, included as a dependency |
+| `opencode` | `@opencode-ai/sdk` | Optional dependency |
+| `codex` | Built-in | JSON-RPC over stdio |
+
+Each provider implements the `AgentProvider` interface with `headless` and `interactive` sub-providers for non-interactive and interactive sessions respectively.
+
+## Key Services
+
+| Service | Description |
+|---------|-------------|
+| `AgentRegistry` | Register and look up agents by role/name |
+| `DispatchService` | Match ready tasks to available workers |
+| `DispatchDaemon` | Continuous polling loop for auto-dispatch |
+| `TaskAssignmentService` | Assign tasks with orchestrator metadata |
+| `WorkerTaskService` | Worker-side task operations (complete, hand off, request help) |
+| `MergeStewardService` | Review and merge completed work branches |
+| `HealthStewardService` | Monitor agent health and restart stale sessions |
+| `StewardScheduler` | Run stewards on cron-like schedules |
+| `RoleDefinitionService` | Store and retrieve agent role definitions |
+| `AgentPoolService` | Manage pools of workers with auto-scaling |
+
+## Git Worktree Isolation
+
+Workers operate in isolated Git worktrees to prevent conflicts:
+
+- **Ephemeral workers:** `agent/{worker-name}/{task-id}-{slug}`
+- **Persistent workers:** `agent/{worker-name}/session-{timestamp}`
+
+Utilities for creating, listing, and cleaning up worktrees are available in the `./git` entry point.
+
+## Entry Points
+
+| Import | Contents |
+|--------|----------|
+| `@stoneforge/smithy` | Everything (re-exports all subpaths) |
+| `@stoneforge/smithy/types` | Agent roles, metadata, message types, naming utilities |
+| `@stoneforge/smithy/services` | All orchestration services |
+| `@stoneforge/smithy/runtime` | Runtime utilities for agent execution |
+| `@stoneforge/smithy/git` | Git worktree management |
+| `@stoneforge/smithy/testing` | Test helpers and mocks |
+| `@stoneforge/smithy/providers` | `AgentProvider` interface, provider registry, all providers |
+
+---
+
+Part of [Stoneforge](https://github.com/stoneforge-ai/stoneforge) — Apache-2.0

package/dist/api/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Orchestrator API
+ *
+ * This module exports the OrchestratorAPI interface and implementation.
+ */
+export { type AgentEntity, isAgentEntity, getAgentMetadata, type OrchestratorAPI, OrchestratorAPIImpl, createOrchestratorAPI, } from './orchestrator-api.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/api/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/api/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EACL,KAAK,WAAW,EAChB,aAAa,EACb,gBAAgB,EAChB,KAAK,eAAe,EACpB,mBAAmB,EACnB,qBAAqB,GACtB,MAAM,uBAAuB,CAAC"}

package/dist/api/index.js

@@ -0,0 +1,7 @@
+/**
+ * Orchestrator API
+ *
+ * This module exports the OrchestratorAPI interface and implementation.
+ */
+export { isAgentEntity, getAgentMetadata, OrchestratorAPIImpl, createOrchestratorAPI, } from './orchestrator-api.js';
+//# sourceMappingURL=index.js.map

package/dist/api/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/api/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAEL,aAAa,EACb,gBAAgB,EAEhB,mBAAmB,EACnB,qBAAqB,GACtB,MAAM,uBAAuB,CAAC"}

package/dist/api/orchestrator-api.d.ts

@@ -0,0 +1,153 @@
+/**
+ * Orchestrator API Implementation
+ *
+ * This module provides the OrchestratorAPI class that extends QuarryAPI
+ * with orchestration-specific functionality for managing AI agents, their
+ * sessions, and task assignments.
+ *
+ * The OrchestratorAPI wraps an existing QuarryAPI instance and adds:
+ * - Agent registration and management
+ * - Session tracking
+ * - Orchestrator-specific task metadata
+ */
+import type { StorageBackend } from '@stoneforge/storage';
+import { type Entity, type EntityId, type Task, type ChannelId, type ElementId } from '@stoneforge/core';
+import { type QuarryAPI, QuarryAPIImpl } from '@stoneforge/quarry';
+import type { AgentRole, AgentMetadata, RegisterDirectorInput, RegisterWorkerInput, RegisterStewardInput, AgentFilter, OrchestratorTaskMeta } from '../types/index.js';
+/**
+ * An Entity that represents an agent with orchestrator metadata.
+ * The agent-specific metadata is stored under `entity.metadata.agent`
+ */
+export interface AgentEntity extends Entity {
+    metadata: {
+        agent: AgentMetadata;
+        [key: string]: unknown;
+    };
+}
+/**
+ * Type guard to check if an entity is an agent entity
+ */
+export declare function isAgentEntity(entity: Entity): entity is AgentEntity;
+/**
+ * Gets the agent metadata from an entity
+ */
+export declare function getAgentMetadata(entity: Entity): AgentMetadata | undefined;
+/**
+ * Extended API interface for orchestration operations
+ */
+export interface OrchestratorAPI extends QuarryAPI {
+    /**
+     * Registers a Director agent
+     */
+    registerDirector(input: RegisterDirectorInput): Promise<AgentEntity>;
+    /**
+     * Registers a Worker agent
+     */
+    registerWorker(input: RegisterWorkerInput): Promise<AgentEntity>;
+    /**
+     * Registers a Steward agent
+     */
+    registerSteward(input: RegisterStewardInput): Promise<AgentEntity>;
+    /**
+     * Gets an agent by ID
+     */
+    getAgent(entityId: EntityId): Promise<AgentEntity | undefined>;
+    /**
+     * Gets an agent by name
+     */
+    getAgentByName(name: string): Promise<AgentEntity | undefined>;
+    /**
+     * Lists agents matching the filter
+     */
+    listAgents(filter?: AgentFilter): Promise<AgentEntity[]>;
+    /**
+     * Gets all agents with a specific role
+     */
+    getAgentsByRole(role: AgentRole): Promise<AgentEntity[]>;
+    /**
+     * Gets available workers (idle or running but accepting tasks)
+     */
+    getAvailableWorkers(): Promise<AgentEntity[]>;
+    /**
+     * Gets all stewards
+     */
+    getStewards(): Promise<AgentEntity[]>;
+    /**
+     * Gets the Director agent (there should be only one per workspace)
+     */
+    getDirector(): Promise<AgentEntity | undefined>;
+    /**
+     * Updates an agent's session status
+     */
+    updateAgentSession(entityId: EntityId, sessionId: string | undefined, status: 'idle' | 'running' | 'suspended' | 'terminated'): Promise<AgentEntity>;
+    /**
+     * Gets the agent's channel for receiving messages
+     */
+    getAgentChannel(entityId: EntityId): Promise<ChannelId | undefined>;
+    /**
+     * Sets orchestrator metadata on a task
+     */
+    setTaskOrchestratorMeta(taskId: ElementId, meta: OrchestratorTaskMeta): Promise<Task>;
+    /**
+     * Updates orchestrator metadata on a task
+     */
+    updateTaskOrchestratorMeta(taskId: ElementId, updates: Partial<OrchestratorTaskMeta>): Promise<Task>;
+    /**
+     * Gets orchestrator metadata from a task
+     */
+    getTaskOrchestratorMeta(taskId: ElementId): Promise<OrchestratorTaskMeta | undefined>;
+    /**
+     * Assigns a task to an agent (sets orchestrator metadata)
+     */
+    assignTaskToAgent(taskId: ElementId, agentId: EntityId, options?: {
+        branch?: string;
+        worktree?: string;
+        sessionId?: string;
+        markAsStarted?: boolean;
+    }): Promise<Task>;
+}
+/**
+ * OrchestratorAPI implementation that extends QuarryAPIImpl
+ */
+export declare class OrchestratorAPIImpl extends QuarryAPIImpl implements OrchestratorAPI {
+    constructor(backend: StorageBackend);
+    registerDirector(input: RegisterDirectorInput): Promise<AgentEntity>;
+    registerWorker(input: RegisterWorkerInput): Promise<AgentEntity>;
+    registerSteward(input: RegisterStewardInput): Promise<AgentEntity>;
+    getAgent(entityId: EntityId): Promise<AgentEntity | undefined>;
+    getAgentByName(name: string): Promise<AgentEntity | undefined>;
+    listAgents(filter?: AgentFilter): Promise<AgentEntity[]>;
+    getAgentsByRole(role: AgentRole): Promise<AgentEntity[]>;
+    getAvailableWorkers(): Promise<AgentEntity[]>;
+    getStewards(): Promise<AgentEntity[]>;
+    getDirector(): Promise<AgentEntity | undefined>;
+    updateAgentSession(entityId: EntityId, sessionId: string | undefined, status: 'idle' | 'running' | 'suspended' | 'terminated'): Promise<AgentEntity>;
+    getAgentChannel(entityId: EntityId): Promise<ChannelId | undefined>;
+    setTaskOrchestratorMeta(taskId: ElementId, meta: OrchestratorTaskMeta): Promise<Task>;
+    updateTaskOrchestratorMeta(taskId: ElementId, updates: Partial<OrchestratorTaskMeta>): Promise<Task>;
+    getTaskOrchestratorMeta(taskId: ElementId): Promise<OrchestratorTaskMeta | undefined>;
+    assignTaskToAgent(taskId: ElementId, agentId: EntityId, options?: {
+        branch?: string;
+        worktree?: string;
+        sessionId?: string;
+        markAsStarted?: boolean;
+    }): Promise<Task>;
+    /**
+     * Creates a dedicated channel for an agent
+     *
+     * @param agentName - The name of the agent (used for channel naming)
+     * @param agentId - The ID of the agent entity (used for membership)
+     * @param createdBy - The entity that created the agent (will be a channel member)
+     * @returns The created channel
+     */
+    private createAgentChannel;
+    /**
+     * Updates an agent's metadata
+     */
+    private updateAgentMetadata;
+}
+/**
+ * Creates an OrchestratorAPI instance
+ */
+export declare function createOrchestratorAPI(backend: StorageBackend): OrchestratorAPI;
+//# sourceMappingURL=orchestrator-api.d.ts.map

package/dist/api/orchestrator-api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"orchestrator-api.d.ts","sourceRoot":"","sources":["../../src/api/orchestrator-api.ts"],"names":[],"mappings":"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"}