@stoneforge/smithy 0.1.0

package/dist/types/role-definition.d.ts

@@ -0,0 +1,272 @@
+/**
+ * Agent Role Definition Types
+ *
+ * This module defines the types for agent role definitions, which store
+ * system prompts and behavioral configurations for agents.
+ *
+ * Role definitions allow agents to be configured with:
+ * - System prompts stored as Documents
+ * - Behavioral hooks for startup, task assignment, and stuck scenarios
+ *
+ * The system prompt is stored as a Document element, allowing versioning
+ * and easy editing. The role definition references this document via its ID.
+ */
+import type { DocumentId, EntityId, Timestamp, ElementId } from '@stoneforge/core';
+import type { AgentRole, WorkerMode, StewardFocus } from './agent.js';
+/**
+ * Behavioral hooks for agents - scripts or prompts to execute on specific events
+ */
+export interface AgentBehaviors {
+    /**
+     * Instruction/prompt fragment appended to the agent's context on startup.
+     * This can include workspace-specific context, conventions, or guidelines.
+     */
+    readonly onStartup?: string;
+    /**
+     * Instruction/prompt fragment appended when a task is assigned to the agent.
+     * Can include task-specific guidelines or workflow requirements.
+     */
+    readonly onTaskAssigned?: string;
+    /**
+     * Instruction/prompt fragment appended when the agent appears stuck
+     * (detected by Health Steward). Can include debugging hints or escalation paths.
+     */
+    readonly onStuck?: string;
+    /**
+     * Instruction/prompt fragment appended before the agent creates a handoff.
+     * Can include guidelines for context preservation.
+     */
+    readonly onHandoff?: string;
+    /**
+     * Instruction/prompt fragment for handling errors or failures.
+     */
+    readonly onError?: string;
+}
+/**
+ * Base interface for all role definitions
+ */
+export interface BaseRoleDefinition {
+    /**
+     * The role type this definition applies to
+     */
+    readonly role: AgentRole;
+    /**
+     * Human-readable name for this role definition (e.g., "Default Director", "Frontend Worker")
+     */
+    readonly name: string;
+    /**
+     * Optional description of this role definition
+     */
+    readonly description?: string;
+    /**
+     * Reference to the Document containing the system prompt for this role.
+     * The document should contain the full system prompt text.
+     */
+    readonly systemPromptRef: DocumentId;
+    /**
+     * Maximum number of concurrent tasks for agents using this role.
+     * Default is 1.
+     */
+    readonly maxConcurrentTasks?: number;
+    /**
+     * Behavioral hooks - prompts/instructions for specific events
+     */
+    readonly behaviors?: AgentBehaviors;
+    /**
+     * Optional tags for categorization
+     */
+    readonly tags?: readonly string[];
+    /**
+     * When this role definition was created
+     */
+    readonly createdAt: Timestamp;
+    /**
+     * Who created this role definition
+     */
+    readonly createdBy: EntityId;
+    /**
+     * When this role definition was last updated
+     */
+    readonly updatedAt: Timestamp;
+}
+/**
+ * Director-specific role definition
+ */
+export interface DirectorRoleDefinition extends BaseRoleDefinition {
+    readonly role: 'director';
+}
+/**
+ * Worker-specific role definition
+ */
+export interface WorkerRoleDefinition extends BaseRoleDefinition {
+    readonly role: 'worker';
+    /**
+     * The worker mode this definition is designed for.
+     * If not specified, applies to both ephemeral and persistent workers.
+     */
+    readonly workerMode?: WorkerMode;
+}
+/**
+ * Steward-specific role definition
+ */
+export interface StewardRoleDefinition extends BaseRoleDefinition {
+    readonly role: 'steward';
+    /**
+     * The steward focus area this definition is designed for.
+     * If not specified, applies to all steward types.
+     */
+    readonly stewardFocus?: StewardFocus;
+}
+/**
+ * Union type for all role definitions
+ */
+export type AgentRoleDefinition = DirectorRoleDefinition | WorkerRoleDefinition | StewardRoleDefinition;
+/**
+ * Input for creating a role definition
+ */
+export interface CreateRoleDefinitionInput {
+    /**
+     * The role type this definition applies to
+     */
+    readonly role: AgentRole;
+    /**
+     * Human-readable name for this role definition
+     */
+    readonly name: string;
+    /**
+     * Optional description
+     */
+    readonly description?: string;
+    /**
+     * The system prompt content (will be stored as a Document)
+     */
+    readonly systemPrompt: string;
+    /**
+     * Maximum number of concurrent tasks (default: 1)
+     */
+    readonly maxConcurrentTasks?: number;
+    /**
+     * Behavioral hooks
+     */
+    readonly behaviors?: AgentBehaviors;
+    /**
+     * Optional tags
+     */
+    readonly tags?: string[];
+    /**
+     * Who is creating this definition
+     */
+    readonly createdBy: EntityId;
+    /**
+     * For workers: the specific worker mode this applies to
+     */
+    readonly workerMode?: WorkerMode;
+    /**
+     * For stewards: the specific steward focus this applies to
+     */
+    readonly stewardFocus?: StewardFocus;
+}
+/**
+ * Input for updating a role definition
+ */
+export interface UpdateRoleDefinitionInput {
+    /**
+     * New name
+     */
+    readonly name?: string;
+    /**
+     * New description
+     */
+    readonly description?: string;
+    /**
+     * New system prompt content (will create new Document version)
+     */
+    readonly systemPrompt?: string;
+    /**
+     * Updated max concurrent tasks
+     */
+    readonly maxConcurrentTasks?: number;
+    /**
+     * Updated behaviors (merged with existing)
+     */
+    readonly behaviors?: Partial<AgentBehaviors>;
+    /**
+     * New tags (replaces existing)
+     */
+    readonly tags?: string[];
+}
+/**
+ * A role definition as stored in the database.
+ * Role definitions are stored as Documents with JSON content type.
+ */
+export interface StoredRoleDefinition {
+    /**
+     * The element ID of the Document storing this role definition
+     */
+    readonly id: ElementId;
+    /**
+     * The role definition data
+     */
+    readonly definition: AgentRoleDefinition;
+}
+/**
+ * Type guard for AgentBehaviors
+ */
+export declare function isAgentBehaviors(value: unknown): value is AgentBehaviors;
+/**
+ * Type guard for DirectorRoleDefinition
+ */
+export declare function isDirectorRoleDefinition(value: unknown): value is DirectorRoleDefinition;
+/**
+ * Type guard for WorkerRoleDefinition
+ */
+export declare function isWorkerRoleDefinition(value: unknown): value is WorkerRoleDefinition;
+/**
+ * Type guard for StewardRoleDefinition
+ */
+export declare function isStewardRoleDefinition(value: unknown): value is StewardRoleDefinition;
+/**
+ * Type guard for any AgentRoleDefinition
+ */
+export declare function isAgentRoleDefinition(value: unknown): value is AgentRoleDefinition;
+/**
+ * Filter options for querying role definitions
+ */
+export interface RoleDefinitionFilter {
+    /**
+     * Filter by role type
+     */
+    readonly role?: AgentRole;
+    /**
+     * Filter by worker mode (only applies when role is 'worker')
+     */
+    readonly workerMode?: WorkerMode;
+    /**
+     * Filter by steward focus (only applies when role is 'steward')
+     */
+    readonly stewardFocus?: StewardFocus;
+    /**
+     * Filter by tags (must have ALL specified tags)
+     */
+    readonly tags?: readonly string[];
+    /**
+     * Filter by name (partial match, case-insensitive)
+     */
+    readonly nameContains?: string;
+}
+/**
+ * Tags used to identify role definition documents
+ */
+export declare const ROLE_DEFINITION_TAGS: {
+    /** Main tag for all role definition documents */
+    readonly ROLE_DEFINITION: "role-definition";
+    /** Tag prefix for role type (e.g., 'role:director') */
+    readonly ROLE_PREFIX: "role:";
+    /** Tag prefix for agent prompt documents */
+    readonly AGENT_PROMPT: "agent-prompt";
+};
+/**
+ * Generates tags for a role definition document
+ */
+export declare function generateRoleDefinitionTags(role: AgentRole, additionalTags?: string[]): string[];
+//# sourceMappingURL=role-definition.d.ts.map

package/dist/types/role-definition.d.ts.map

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

package/dist/types/role-definition.js

@@ -0,0 +1,144 @@
+/**
+ * Agent Role Definition Types
+ *
+ * This module defines the types for agent role definitions, which store
+ * system prompts and behavioral configurations for agents.
+ *
+ * Role definitions allow agents to be configured with:
+ * - System prompts stored as Documents
+ * - Behavioral hooks for startup, task assignment, and stuck scenarios
+ *
+ * The system prompt is stored as a Document element, allowing versioning
+ * and easy editing. The role definition references this document via its ID.
+ */
+// ============================================================================
+// Type Guards
+// ============================================================================
+/**
+ * Type guard for AgentBehaviors
+ */
+export function isAgentBehaviors(value) {
+    if (typeof value !== 'object' || value === null) {
+        return false;
+    }
+    const obj = value;
+    // All fields are optional strings
+    const optionalStringFields = ['onStartup', 'onTaskAssigned', 'onStuck', 'onHandoff', 'onError'];
+    for (const field of optionalStringFields) {
+        if (obj[field] !== undefined && typeof obj[field] !== 'string') {
+            return false;
+        }
+    }
+    return true;
+}
+/**
+ * Type guard for DirectorRoleDefinition
+ */
+export function isDirectorRoleDefinition(value) {
+    if (!isBaseRoleDefinition(value)) {
+        return false;
+    }
+    return value.role === 'director';
+}
+/**
+ * Type guard for WorkerRoleDefinition
+ */
+export function isWorkerRoleDefinition(value) {
+    if (!isBaseRoleDefinition(value)) {
+        return false;
+    }
+    const def = value;
+    if (def.role !== 'worker') {
+        return false;
+    }
+    // workerMode is optional, but if present must be valid
+    if (def.workerMode !== undefined && def.workerMode !== 'ephemeral' && def.workerMode !== 'persistent') {
+        return false;
+    }
+    return true;
+}
+/**
+ * Type guard for StewardRoleDefinition
+ */
+export function isStewardRoleDefinition(value) {
+    if (!isBaseRoleDefinition(value)) {
+        return false;
+    }
+    const def = value;
+    if (def.role !== 'steward') {
+        return false;
+    }
+    // stewardFocus is optional, but if present must be valid
+    const validFoci = ['merge', 'health', 'reminder', 'ops', 'docs'];
+    if (def.stewardFocus !== undefined && !validFoci.includes(def.stewardFocus)) {
+        return false;
+    }
+    return true;
+}
+/**
+ * Type guard for any AgentRoleDefinition
+ */
+export function isAgentRoleDefinition(value) {
+    return isDirectorRoleDefinition(value) || isWorkerRoleDefinition(value) || isStewardRoleDefinition(value);
+}
+/**
+ * Type guard for base role definition structure
+ */
+function isBaseRoleDefinition(value) {
+    if (typeof value !== 'object' || value === null) {
+        return false;
+    }
+    const obj = value;
+    // Required fields
+    if (typeof obj.role !== 'string')
+        return false;
+    if (typeof obj.name !== 'string')
+        return false;
+    if (typeof obj.systemPromptRef !== 'string')
+        return false;
+    if (typeof obj.createdAt !== 'string')
+        return false;
+    if (typeof obj.createdBy !== 'string')
+        return false;
+    if (typeof obj.updatedAt !== 'string')
+        return false;
+    // Optional fields
+    if (obj.maxConcurrentTasks !== undefined && typeof obj.maxConcurrentTasks !== 'number')
+        return false;
+    if (obj.description !== undefined && typeof obj.description !== 'string')
+        return false;
+    if (obj.behaviors !== undefined && !isAgentBehaviors(obj.behaviors))
+        return false;
+    if (obj.tags !== undefined && !Array.isArray(obj.tags))
+        return false;
+    return true;
+}
+// ============================================================================
+// Constants
+// ============================================================================
+/**
+ * Tags used to identify role definition documents
+ */
+export const ROLE_DEFINITION_TAGS = {
+    /** Main tag for all role definition documents */
+    ROLE_DEFINITION: 'role-definition',
+    /** Tag prefix for role type (e.g., 'role:director') */
+    ROLE_PREFIX: 'role:',
+    /** Tag prefix for agent prompt documents */
+    AGENT_PROMPT: 'agent-prompt',
+};
+/**
+ * Generates tags for a role definition document
+ */
+export function generateRoleDefinitionTags(role, additionalTags) {
+    const tags = [
+        ROLE_DEFINITION_TAGS.ROLE_DEFINITION,
+        ROLE_DEFINITION_TAGS.AGENT_PROMPT,
+        `${ROLE_DEFINITION_TAGS.ROLE_PREFIX}${role}`,
+    ];
+    if (additionalTags) {
+        tags.push(...additionalTags);
+    }
+    return tags;
+}
+//# sourceMappingURL=role-definition.js.map

package/dist/types/role-definition.js.map

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

package/dist/types/task-meta.d.ts

@@ -0,0 +1,248 @@
+/**
+ * Orchestrator Task Metadata Types
+ *
+ * This module defines the metadata structure for tasks in the orchestration system.
+ * Tasks gain additional metadata when managed by the orchestrator to track:
+ * - Git branch association
+ * - Worktree location
+ * - Claude Code session ID for resumption
+ *
+ * This metadata is stored in the task's `metadata` field alongside any existing
+ * task metadata.
+ */
+import type { EntityId, ElementId, Timestamp } from '@stoneforge/core';
+/**
+ * Orchestrator-specific metadata attached to tasks managed by the orchestration system.
+ *
+ * This is stored in the task's `metadata` field under the `orchestrator` key:
+ * ```typescript
+ * task.metadata = {
+ *   ...existingMetadata,
+ *   orchestrator: OrchestratorTaskMeta
+ * }
+ * ```
+ */
+export interface OrchestratorTaskMeta {
+    /** Git branch created for this task (e.g., "agent/alice/task-123-implement-feature") */
+    readonly branch?: string;
+    /** Path to the worktree where the agent is working (e.g., ".stoneforge/.worktrees/alice-implement-feature/") */
+    readonly worktree?: string;
+    /** Claude Code session ID for this task, enabling session resumption */
+    readonly sessionId?: string;
+    /** Entity ID of the agent assigned to this task */
+    readonly assignedAgent?: EntityId;
+    /** When the agent started working on this task */
+    readonly startedAt?: Timestamp;
+    /** When the agent completed this task (before merge) */
+    readonly completedAt?: Timestamp;
+    /** When the branch was merged */
+    readonly mergedAt?: Timestamp;
+    /** Merge status tracking */
+    readonly mergeStatus?: MergeStatus;
+    /** If merge failed, the reason */
+    readonly mergeFailureReason?: string;
+    /** Number of times tests have been run on this branch */
+    readonly testRunCount?: number;
+    /** Last test result */
+    readonly lastTestResult?: TestResult;
+    /** Number of times this task has been reconciled from a closed-but-unmerged state */
+    readonly reconciliationCount?: number;
+    /** Number of times this task has been recovered from a stuck merging/testing state */
+    readonly stuckMergeRecoveryCount?: number;
+    /**
+     * Set of issue types that have been reported for this task.
+     * Prevents duplicate messages/fix tasks for the same type of issue.
+     * Format: "test_failure", "merge_conflict", etc.
+     */
+    readonly reportedIssues?: readonly string[];
+    /** Branch preserved from handoff (may differ from current branch if not yet continued) */
+    readonly handoffBranch?: string;
+    /** Worktree path preserved from handoff */
+    readonly handoffWorktree?: string;
+    /** Session ID of the last agent that worked on this task before handoff */
+    readonly lastSessionId?: string;
+    /** Timestamp when the task was handed off */
+    readonly handoffAt?: Timestamp;
+    /** Entity ID of the agent who handed off the task */
+    readonly handoffFrom?: EntityId;
+    /** URL of the merge request created for this task */
+    readonly mergeRequestUrl?: string;
+    /** Merge request identifier (e.g. PR number) */
+    readonly mergeRequestId?: number;
+    /** Which provider created the merge request (e.g. 'github', 'local') */
+    readonly mergeRequestProvider?: string;
+    /** Completion summary provided by the agent */
+    readonly completionSummary?: string;
+    /** Last commit hash before completion */
+    readonly lastCommitHash?: string;
+    /** History of all handoffs for this task */
+    readonly handoffHistory?: HandoffHistoryEntry[];
+    /** History of all sessions (worker and steward) that worked on this task */
+    readonly sessionHistory?: readonly TaskSessionHistoryEntry[];
+    /** Result of the most recent branch sync with master */
+    readonly lastSyncResult?: SyncResultMeta;
+}
+/**
+ * Metadata about a branch sync operation result
+ */
+export interface SyncResultMeta {
+    /** Whether the sync succeeded without conflicts */
+    readonly success: boolean;
+    /** List of conflicted file paths (if any) */
+    readonly conflicts?: string[];
+    /** Error message (if sync failed for non-conflict reasons) */
+    readonly error?: string;
+    /** Human-readable message */
+    readonly message: string;
+    /** When the sync was performed */
+    readonly syncedAt: Timestamp;
+}
+/**
+ * An entry in the handoff history for a task
+ */
+export interface HandoffHistoryEntry {
+    /** Session ID of the agent that handed off */
+    readonly sessionId: string;
+    /** Message explaining why the handoff occurred */
+    readonly message?: string;
+    /** Branch at time of handoff */
+    readonly branch?: string;
+    /** Worktree at time of handoff */
+    readonly worktree?: string;
+    /** When the handoff occurred */
+    readonly handoffAt: Timestamp;
+}
+/**
+ * An entry in the session history for a task, tracking all sessions (worker and steward)
+ * that have worked on this task.
+ */
+export interface TaskSessionHistoryEntry {
+    /** Internal session ID (used to fetch messages via GET /api/sessions/:id/messages) */
+    readonly sessionId: string;
+    /** Provider session ID (for resume) */
+    readonly providerSessionId?: string;
+    /** Entity ID of the agent */
+    readonly agentId: EntityId;
+    /** Display name of the agent */
+    readonly agentName: string;
+    /** Role of the agent */
+    readonly agentRole: 'worker' | 'steward';
+    /** Timestamp when the session started */
+    readonly startedAt: Timestamp;
+    /** Timestamp when the session ended (undefined if still running) */
+    readonly endedAt?: Timestamp;
+}
+/**
+ * Status of the merge process for a completed task's branch
+ */
+export type MergeStatus = 'pending' | 'testing' | 'merging' | 'merged' | 'conflict' | 'test_failed' | 'failed' | 'not_applicable';
+/**
+ * All valid merge status values
+ */
+export declare const MergeStatusValues: readonly ["pending", "testing", "merging", "merged", "conflict", "test_failed", "failed", "not_applicable"];
+/**
+ * Type guard to check if a value is a valid MergeStatus
+ */
+export declare function isMergeStatus(value: unknown): value is MergeStatus;
+/**
+ * Result of running tests on a task's branch
+ */
+export interface TestResult {
+    /** Whether tests passed */
+    readonly passed: boolean;
+    /** Total number of tests run */
+    readonly totalTests?: number;
+    /** Number of tests that passed */
+    readonly passedTests?: number;
+    /** Number of tests that failed */
+    readonly failedTests?: number;
+    /** Number of tests that were skipped */
+    readonly skippedTests?: number;
+    /** When the test run completed */
+    readonly completedAt: Timestamp;
+    /** Duration of the test run in milliseconds */
+    readonly durationMs?: number;
+    /** Error message if tests failed to run */
+    readonly errorMessage?: string;
+}
+/**
+ * Type guard to check if a value is a valid TestResult
+ */
+export declare function isTestResult(value: unknown): value is TestResult;
+/**
+ * Extracts orchestrator metadata from a task's metadata field
+ */
+export declare function getOrchestratorTaskMeta(taskMetadata: Record<string, unknown> | undefined): OrchestratorTaskMeta | undefined;
+/**
+ * Sets orchestrator metadata on a task's metadata field
+ */
+export declare function setOrchestratorTaskMeta(existingMetadata: Record<string, unknown> | undefined, orchestratorMeta: OrchestratorTaskMeta): Record<string, unknown>;
+/**
+ * Updates orchestrator metadata on a task's metadata field
+ */
+export declare function updateOrchestratorTaskMeta(existingMetadata: Record<string, unknown> | undefined, updates: Partial<OrchestratorTaskMeta>): Record<string, unknown>;
+/**
+ * Type guard to validate OrchestratorTaskMeta structure
+ */
+export declare function isOrchestratorTaskMeta(value: unknown): value is OrchestratorTaskMeta;
+/**
+ * Appends a session history entry to the task's orchestrator metadata.
+ * Caps the history at MAX_SESSION_HISTORY_ENTRIES entries.
+ *
+ * @param existingMetadata - The task's existing metadata
+ * @param entry - The session history entry to append
+ * @returns Updated task metadata with the new session history entry
+ */
+export declare function appendTaskSessionHistory(existingMetadata: Record<string, unknown> | undefined, entry: TaskSessionHistoryEntry): Record<string, unknown>;
+/**
+ * Closes a session history entry by setting the endedAt timestamp.
+ * Finds the session history entry matching the sessionId that has no endedAt.
+ *
+ * @param existingMetadata - The task's existing metadata
+ * @param sessionId - The session ID to close
+ * @param endedAt - The timestamp when the session ended
+ * @returns Updated task metadata with the closed session history entry
+ */
+export declare function closeTaskSessionHistory(existingMetadata: Record<string, unknown> | undefined, sessionId: string, endedAt: Timestamp): Record<string, unknown>;
+/**
+ * Generates a branch name for an agent working on a task
+ *
+ * Format: agent/{worker-name}/{task-id}-{slug}
+ *
+ * @param workerName - The agent's name
+ * @param taskId - The task ID
+ * @param slug - URL-friendly slug derived from task title (optional)
+ */
+export declare function generateBranchName(workerName: string, taskId: ElementId, slug?: string): string;
+/**
+ * Generates a worktree path for an agent working on a task
+ *
+ * Format: .stoneforge/.worktrees/{worker-name}-{task-slug}/
+ *
+ * @param workerName - The agent's name
+ * @param slug - URL-friendly slug derived from task title (optional)
+ */
+export declare function generateWorktreePath(workerName: string, slug?: string): string;
+/**
+ * Generates a branch name for a persistent worker session
+ *
+ * Format: session/{worker-name}-{timestamp}
+ *
+ * @param workerName - The agent's name
+ * @param timestamp - Timestamp string (e.g. '20240115143022')
+ */
+export declare function generateSessionBranchName(workerName: string, timestamp: string): string;
+/**
+ * Generates a worktree path for a persistent worker session
+ *
+ * Format: .stoneforge/.worktrees/{worker-name}-session-{timestamp}/
+ *
+ * @param workerName - The agent's name
+ * @param timestamp - Timestamp string (e.g. '20240115143022')
+ */
+export declare function generateSessionWorktreePath(workerName: string, timestamp: string): string;
+/**
+ * Creates a URL-friendly slug from a task title
+ */
+export declare function createSlugFromTitle(title: string): string;
+//# sourceMappingURL=task-meta.d.ts.map