dot-agents 0.5.0 → 0.7.4

package/dist/lib/registry.js

@@ -0,0 +1,192 @@
+import { readFile, writeFile, mkdir } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { homedir } from "node:os";
+import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
+const CONFIG_DIR = join(homedir(), ".config", "dot-agents");
+const REGISTRY_FILE = "projects.yaml";
+/**
+ * Get path to the projects registry file
+ */
+export function getRegistryPath() {
+    return join(CONFIG_DIR, REGISTRY_FILE);
+}
+/**
+ * Load the project registry
+ */
+export async function loadRegistry() {
+    const registryPath = getRegistryPath();
+    try {
+        const content = await readFile(registryPath, "utf-8");
+        const data = parseYaml(content);
+        return data || { projects: {} };
+    }
+    catch {
+        return { projects: {} };
+    }
+}
+/**
+ * Save the project registry
+ */
+export async function saveRegistry(registry) {
+    await mkdir(CONFIG_DIR, { recursive: true });
+    const registryPath = getRegistryPath();
+    const content = stringifyYaml(registry);
+    await writeFile(registryPath, content, "utf-8");
+}
+/**
+ * Register a project in the registry
+ */
+export async function registerProject(name, path) {
+    const registry = await loadRegistry();
+    // Expand ~ to home directory
+    const expandedPath = path.startsWith("~")
+        ? join(homedir(), path.slice(1))
+        : resolve(path);
+    registry.projects[name] = expandedPath;
+    await saveRegistry(registry);
+}
+/**
+ * Unregister a project from the registry
+ */
+export async function unregisterProject(name) {
+    const registry = await loadRegistry();
+    if (name in registry.projects) {
+        delete registry.projects[name];
+        await saveRegistry(registry);
+        return true;
+    }
+    return false;
+}
+/**
+ * Resolve a project name to its .agents path
+ */
+export async function resolveProject(name) {
+    const registry = await loadRegistry();
+    const path = registry.projects[name];
+    if (!path) {
+        return null;
+    }
+    // Expand ~ if present (in case registry was edited manually)
+    return path.startsWith("~") ? join(homedir(), path.slice(1)) : path;
+}
+/**
+ * Parse a channel address that may include a project prefix
+ *
+ * Formats:
+ * - @persona (local DM)
+ * - #channel (local public channel)
+ * - @project/persona (cross-project DM)
+ * - #project/channel (cross-project public channel)
+ */
+export function parseChannelAddress(address) {
+    if (!address.startsWith("#") && !address.startsWith("@")) {
+        throw new Error(`Invalid channel address: ${address}. Must start with # or @`);
+    }
+    const type = address[0];
+    const rest = address.slice(1);
+    // Check for project/name format
+    const slashIndex = rest.indexOf("/");
+    if (slashIndex > 0) {
+        const project = rest.slice(0, slashIndex);
+        const name = rest.slice(slashIndex + 1);
+        if (!name) {
+            throw new Error(`Invalid channel address: ${address}. Missing channel/persona name after project.`);
+        }
+        return { project, type, name, original: address };
+    }
+    // Local channel
+    return { project: null, type, name: rest, original: address };
+}
+/**
+ * Resolve a channel address to a channels directory and local channel name
+ *
+ * Resolution order for @name (without /):
+ * 1. Check registered projects first - if found, routes to project's @root
+ * 2. Fall back to local persona lookup
+ *
+ * Returns:
+ * - channelsDir: The path to the channels directory (local or remote)
+ * - localChannelName: The channel name within that directory (e.g., @persona, #channel)
+ * - isProjectEntryPoint: True if routed to a project's entry point
+ * - projectName: The project name if routed to a project
+ */
+export async function resolveChannelAddress(address, localChannelsDir) {
+    const parsed = parseChannelAddress(address);
+    if (parsed.project === null) {
+        // Check if @name matches a registered project (unified resolution)
+        if (parsed.type === "@") {
+            const projectPath = await resolveProject(parsed.name);
+            if (projectPath) {
+                // Route to project's entry point (@root)
+                return {
+                    channelsDir: join(projectPath, "channels"),
+                    localChannelName: "@root",
+                    isProjectEntryPoint: true,
+                    projectName: parsed.name,
+                };
+            }
+        }
+        // Local channel (no project match or public channel)
+        return {
+            channelsDir: localChannelsDir,
+            localChannelName: address,
+        };
+    }
+    // Cross-project channel with explicit project/name format
+    const projectPath = await resolveProject(parsed.project);
+    if (!projectPath) {
+        throw new Error(`Unknown project: ${parsed.project}. Register it with: npx dot-agents projects add ${parsed.project} /path/to/project`);
+    }
+    return {
+        channelsDir: join(projectPath, "channels"),
+        localChannelName: `${parsed.type}${parsed.name}`,
+        projectName: parsed.project,
+    };
+}
+/**
+ * List all registered projects
+ */
+export async function listProjects() {
+    const registry = await loadRegistry();
+    return Object.entries(registry.projects).map(([name, path]) => ({
+        name,
+        path,
+    }));
+}
+/**
+ * Get the project name for a given agents directory path
+ * Returns null if the path doesn't match any registered project
+ */
+export async function getProjectNameByPath(agentsDir) {
+    const registry = await loadRegistry();
+    const normalizedPath = agentsDir.replace(/\/$/, ""); // Remove trailing slash
+    for (const [name, path] of Object.entries(registry.projects)) {
+        const normalizedProjectPath = path.replace(/\/$/, "");
+        if (normalizedPath === normalizedProjectPath) {
+            return name;
+        }
+    }
+    return null;
+}
+/**
+ * Detect collisions between registered project names and local persona names.
+ * When a collision exists, @name will route to the project (projects take priority).
+ */
+export async function detectNameCollisions(personaNames) {
+    const registry = await loadRegistry();
+    const collisions = [];
+    for (const [projectName, projectPath] of Object.entries(registry.projects)) {
+        // Check if any persona name matches the project name
+        for (const personaName of personaNames) {
+            if (personaName === projectName) {
+                collisions.push({
+                    name: projectName,
+                    projectPath: projectPath,
+                    personaPath: personaName,
+                });
+            }
+        }
+    }
+    return collisions;
+}
+//# sourceMappingURL=registry.js.map

package/dist/lib/registry.js.map

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

package/dist/lib/session-thread.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Session-as-Thread primitives
+ *
+ * Sessions are threads in the #sessions channel. This provides a simpler
+ * model than the directory-based sessions, with cross-machine coordination
+ * via file sync (since channels are just files).
+ */
+/**
+ * Session start options
+ */
+export interface StartSessionOptions {
+    /** Base channels directory */
+    channelsDir: string;
+    /** Persona name running the session */
+    persona: string;
+    /** Execution mode */
+    mode: "interactive" | "headless";
+    /** What triggered the session */
+    trigger: "manual" | "cron" | "dm" | "channel";
+    /** Session goal/description */
+    goal?: string;
+    /** Upstream return address for delegation callbacks */
+    upstream?: string;
+}
+/**
+ * Active session handle
+ */
+export interface SessionThread {
+    /** Session/thread ID (ISO timestamp) */
+    id: string;
+    /** Path to workspace directory */
+    workspacePath: string;
+    /** Channels directory */
+    channelsDir: string;
+}
+/**
+ * Start a new session by creating a thread in #sessions
+ *
+ * @returns Session handle with thread ID and workspace path
+ */
+export declare function startSession(options: StartSessionOptions): Promise<SessionThread>;
+/**
+ * Post an update to a session thread
+ *
+ * @param session - Session handle or session ID
+ * @param channelsDir - Channels directory (required if session is just an ID)
+ * @param message - Update message content
+ * @param from - Who is posting (defaults to session persona)
+ */
+export declare function updateSession(session: SessionThread | string, channelsDirOrMessage: string, messageOrFrom?: string, from?: string): Promise<string>;
+/**
+ * End session options
+ */
+export interface EndSessionOptions {
+    /** Whether the session completed successfully */
+    success: boolean;
+    /** Exit code */
+    exitCode: number;
+    /** Duration in milliseconds */
+    duration: number;
+    /** Error message if failed */
+    error?: string;
+}
+/**
+ * End a session by posting a completion message
+ *
+ * @param session - Session handle
+ * @param options - End session options
+ */
+export declare function endSession(session: SessionThread, options: EndSessionOptions): Promise<string>;
+/**
+ * Get the workspace path for a session thread
+ */
+export declare function getSessionWorkspace(channelsDir: string, sessionId: string, create?: boolean): Promise<string | null>;
+//# sourceMappingURL=session-thread.d.ts.map

package/dist/lib/session-thread.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-thread.d.ts","sourceRoot":"","sources":["../../src/lib/session-thread.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAYH;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,8BAA8B;IAC9B,WAAW,EAAE,MAAM,CAAC;IACpB,uCAAuC;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,qBAAqB;IACrB,IAAI,EAAE,aAAa,GAAG,UAAU,CAAC;IACjC,iCAAiC;IACjC,OAAO,EAAE,QAAQ,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;IAC9C,+BAA+B;IAC/B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,uDAAuD;IACvD,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,wCAAwC;IACxC,EAAE,EAAE,MAAM,CAAC;IACX,kCAAkC;IAClC,aAAa,EAAE,MAAM,CAAC;IACtB,yBAAyB;IACzB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;GAIG;AACH,wBAAsB,YAAY,CAChC,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,aAAa,CAAC,CA0CxB;AAED;;;;;;;GAOG;AACH,wBAAsB,aAAa,CACjC,OAAO,EAAE,aAAa,GAAG,MAAM,EAC/B,oBAAoB,EAAE,MAAM,EAC5B,aAAa,CAAC,EAAE,MAAM,EACtB,IAAI,CAAC,EAAE,MAAM,GACZ,OAAO,CAAC,MAAM,CAAC,CA+BjB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,iDAAiD;IACjD,OAAO,EAAE,OAAO,CAAC;IACjB,gBAAgB;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,+BAA+B;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,8BAA8B;IAC9B,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;GAKG;AACH,wBAAsB,UAAU,CAC9B,OAAO,EAAE,aAAa,EACtB,OAAO,EAAE,iBAAiB,GACzB,OAAO,CAAC,MAAM,CAAC,CA4BjB;AAsBD;;GAEG;AACH,wBAAsB,mBAAmB,CACvC,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,MAAM,EACjB,MAAM,GAAE,OAAe,GACtB,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAExB"}

package/dist/lib/session-thread.js

@@ -0,0 +1,132 @@
+/**
+ * Session-as-Thread primitives
+ *
+ * Sessions are threads in the #sessions channel. This provides a simpler
+ * model than the directory-based sessions, with cross-machine coordination
+ * via file sync (since channels are just files).
+ */
+import { hostname } from "node:os";
+import { publishMessage, replyToMessage, getThreadWorkspace, } from "./channel.js";
+const SESSIONS_CHANNEL = "#sessions";
+/**
+ * Start a new session by creating a thread in #sessions
+ *
+ * @returns Session handle with thread ID and workspace path
+ */
+export async function startSession(options) {
+    const { channelsDir, persona, mode, trigger, goal, upstream } = options;
+    const host = hostname();
+    // Build the initial session message
+    const lines = [];
+    lines.push("**Session Started**");
+    lines.push("");
+    lines.push(`- **Persona:** ${persona}`);
+    lines.push(`- **Mode:** ${mode}`);
+    lines.push(`- **Trigger:** ${trigger}`);
+    lines.push(`- **Host:** ${host}`);
+    if (goal) {
+        lines.push(`- **Goal:** ${goal}`);
+    }
+    if (upstream) {
+        lines.push(`- **Upstream:** ${upstream}`);
+    }
+    // Publish to #sessions channel
+    const threadId = await publishMessage(channelsDir, SESSIONS_CHANNEL, lines.join("\n"), {
+        from: `session:${persona}`,
+        tags: ["session-start", mode, trigger],
+    });
+    // Create and return workspace path
+    const workspacePath = await getThreadWorkspace(channelsDir, SESSIONS_CHANNEL, threadId, true // create if doesn't exist
+    );
+    if (!workspacePath) {
+        throw new Error(`Failed to create workspace for session ${threadId}`);
+    }
+    return {
+        id: threadId,
+        workspacePath,
+        channelsDir,
+    };
+}
+/**
+ * Post an update to a session thread
+ *
+ * @param session - Session handle or session ID
+ * @param channelsDir - Channels directory (required if session is just an ID)
+ * @param message - Update message content
+ * @param from - Who is posting (defaults to session persona)
+ */
+export async function updateSession(session, channelsDirOrMessage, messageOrFrom, from) {
+    let channelsDir;
+    let threadId;
+    let message;
+    let sender;
+    if (typeof session === "string") {
+        // Called as updateSession(threadId, channelsDir, message, from?)
+        threadId = session;
+        channelsDir = channelsDirOrMessage;
+        message = messageOrFrom;
+        sender = from;
+    }
+    else {
+        // Called as updateSession(session, message, from?)
+        threadId = session.id;
+        channelsDir = session.channelsDir;
+        message = channelsDirOrMessage;
+        sender = messageOrFrom;
+    }
+    const replyId = await replyToMessage(channelsDir, SESSIONS_CHANNEL, threadId, message, {
+        from: sender,
+    });
+    return replyId;
+}
+/**
+ * End a session by posting a completion message
+ *
+ * @param session - Session handle
+ * @param options - End session options
+ */
+export async function endSession(session, options) {
+    const { success, exitCode, duration, error } = options;
+    // Format duration nicely
+    const durationStr = formatDuration(duration);
+    const lines = [];
+    lines.push("**Session Ended**");
+    lines.push("");
+    lines.push(`- **Success:** ${success ? "✓" : "✗"}`);
+    lines.push(`- **Exit Code:** ${exitCode}`);
+    lines.push(`- **Duration:** ${durationStr}`);
+    if (error) {
+        lines.push(`- **Error:** ${error}`);
+    }
+    const replyId = await replyToMessage(session.channelsDir, SESSIONS_CHANNEL, session.id, lines.join("\n"), {
+        from: "system",
+        tags: ["session-end", success ? "success" : "failed"],
+    });
+    return replyId;
+}
+/**
+ * Format duration in human-readable form
+ */
+function formatDuration(ms) {
+    if (ms < 1000) {
+        return `${ms}ms`;
+    }
+    if (ms < 60000) {
+        return `${(ms / 1000).toFixed(1)}s`;
+    }
+    if (ms < 3600000) {
+        const mins = Math.floor(ms / 60000);
+        const secs = Math.floor((ms % 60000) / 1000);
+        return secs > 0 ? `${mins}m ${secs}s` : `${mins}m`;
+    }
+    const hours = Math.floor(ms / 3600000);
+    const mins = Math.floor((ms % 3600000) / 60000);
+    return mins > 0 ? `${hours}h ${mins}m` : `${hours}h`;
+}
+/**
+ * Get the workspace path for a session thread
+ */
+export async function getSessionWorkspace(channelsDir, sessionId, create = false) {
+    return getThreadWorkspace(channelsDir, SESSIONS_CHANNEL, sessionId, create);
+}
+//# sourceMappingURL=session-thread.js.map

package/dist/lib/session-thread.js.map

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

package/dist/lib/session.d.ts

@@ -0,0 +1,150 @@
+/**
+ * Runtime context for the session
+ */
+export interface RuntimeContext {
+    /** Machine hostname */
+    hostname: string;
+    /** How the session is being run */
+    executionMode: "interactive" | "headless";
+    /** What triggered the session */
+    triggerType: "manual" | "cron" | "dm" | "channel";
+    /** Working directory for the session */
+    workingDir: string;
+}
+/**
+ * Metadata stored in session.md frontmatter
+ */
+export interface SessionMetadata {
+    /** Unique session ID (matches directory name) */
+    id: string;
+    /** When session started */
+    started: string;
+    /** When session ended (set on finalize) */
+    ended?: string;
+    /** What this session is trying to accomplish */
+    goal?: string;
+    /** Runtime context */
+    runtime: RuntimeContext;
+    /**
+     * Upstream return address - where to send completions/escalations
+     * Format: "@project:persona --session-id <id>" or "@persona" for local
+     * Examples:
+     *   "@odin:dottie --session-id 2025-12-22T15-30-45"
+     *   "@developer"
+     *   null (for top-level interactive sessions)
+     */
+    upstream?: string;
+    /** Persona info */
+    persona?: {
+        name: string;
+        inheritanceChain?: string[];
+    };
+    /** Workflow info (if running a workflow) */
+    workflow?: {
+        name: string;
+        path?: string;
+        inputs?: Record<string, unknown>;
+    };
+    /** Execution results (set on finalize) */
+    result?: {
+        success: boolean;
+        exitCode: number;
+        duration: number;
+        error?: string;
+    };
+}
+/**
+ * Info about a session for listing
+ */
+export interface SessionInfo {
+    /** Directory name (also the session ID) */
+    id: string;
+    /** Full path to session directory */
+    path: string;
+    /** When session started */
+    timestamp: Date;
+    /** Session metadata from frontmatter */
+    metadata?: SessionMetadata;
+}
+/**
+ * Options for creating a session
+ */
+export interface CreateSessionOptions {
+    /** Base sessions directory */
+    sessionsDir: string;
+    /** Runtime context */
+    runtime: RuntimeContext;
+    /** Upstream return address (e.g., "@odin:dottie --session-id abc123") */
+    upstream?: string;
+    /** Goal/description for this session */
+    goal?: string;
+    /** Persona info */
+    persona?: {
+        name: string;
+        inheritanceChain?: string[];
+    };
+    /** Workflow info */
+    workflow?: {
+        name: string;
+        path?: string;
+        inputs?: Record<string, unknown>;
+    };
+}
+/**
+ * Active session handle
+ */
+export interface Session {
+    /** Session ID (directory name) */
+    id: string;
+    /** Full path to session directory */
+    path: string;
+    /** Path to session.md */
+    sessionFile: string;
+    /** Session metadata */
+    metadata: SessionMetadata;
+    /** Session content (body of session.md, without frontmatter) */
+    content?: string;
+}
+/**
+ * Generate session ID from timestamp
+ * Format: YYYY-MM-DDTHH-MM-SS (sortable, filesystem-safe)
+ */
+export declare function generateSessionId(date?: Date): string;
+/**
+ * Parse session ID back to Date
+ */
+export declare function parseSessionId(id: string): Date | null;
+/**
+ * Create a new session directory and initial session.md
+ */
+export declare function createSession(options: CreateSessionOptions): Promise<Session>;
+/**
+ * Options for finalizing a session
+ */
+export interface FinalizeSessionOptions {
+    /** Whether execution succeeded */
+    success: boolean;
+    /** Exit code from process */
+    exitCode: number;
+    /** Duration in milliseconds */
+    duration: number;
+    /** Error message if failed */
+    error?: string;
+    /** Standard output to append to log */
+    stdout?: string;
+    /** Standard error to append to log */
+    stderr?: string;
+}
+/**
+ * Finalize a session with execution results
+ */
+export declare function finalizeSession(session: Session, options: FinalizeSessionOptions): Promise<void>;
+/**
+ * Get recent sessions from sessions directory
+ */
+export declare function getRecentSessions(sessionsDir: string, limit?: number): Promise<SessionInfo[]>;
+/**
+ * Read a session by ID
+ */
+export declare function readSession(sessionsDir: string, sessionId: string): Promise<Session | null>;
+//# sourceMappingURL=session.d.ts.map

package/dist/lib/session.d.ts.map

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