youmd 0.8.28 → 0.9.0

package/dist/lib/daemon.js

@@ -34,10 +34,14 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.YOUMD_DAEMONS = void 0;
+exports.detectDaemonBackend = detectDaemonBackend;
+exports.hasUserSystemd = hasUserSystemd;
 exports.expandHome = expandHome;
 exports.tailUsefulLine = tailUsefulLine;
 exports.newestMtimeIso = newestMtimeIso;
 exports.isLaunchAgentLoaded = isLaunchAgentLoaded;
+exports.isSystemdUnitActive = isSystemdUnitActive;
+exports.isDaemonLoaded = isDaemonLoaded;
 exports.getDaemonHealth = getDaemonHealth;
 const child_process = __importStar(require("child_process"));
 const fs = __importStar(require("fs"));
@@ -57,6 +61,7 @@ exports.YOUMD_DAEMONS = [
         intervalSeconds: 0,
         stdoutLog: runtimeLogPath("realtime-sync.out.log"),
         stderrLog: runtimeLogPath("realtime-sync.err.log"),
+        linuxUnit: "you-realtime-sync.service",
     },
     {
         label: "com.you.skillstack-sync",
@@ -67,6 +72,7 @@ exports.YOUMD_DAEMONS = [
         stdoutLog: runtimeLogPath("skillstack-sync.out.log"),
         stderrLog: runtimeLogPath("skillstack-sync.err.log"),
         combinedLog: runtimeLogPath("skillstack-sync.log"),
+        linuxUnit: "you-skillstack-sync.timer",
     },
     {
         label: "com.you.identity-sync",
@@ -76,6 +82,7 @@ exports.YOUMD_DAEMONS = [
         intervalSeconds: 300,
         stdoutLog: runtimeLogPath("identity-sync.out.log"),
         stderrLog: runtimeLogPath("identity-sync.err.log"),
+        linuxUnit: "you-identity-sync.timer",
     },
     {
         label: "com.you.context-sync",
@@ -86,8 +93,50 @@ exports.YOUMD_DAEMONS = [
         stdoutLog: runtimeLogPath("context-sync.out.log"),
         stderrLog: runtimeLogPath("context-sync.err.log"),
         combinedLog: runtimeLogPath("context-sync.log"),
+        linuxUnit: "you-context-sync.timer",
+    },
+    {
+        label: "com.you.orchestrator-watch",
+        name: "orchestrator report-back",
+        command: "you orchestrate watch --once",
+        intervalSeconds: 60,
+        stdoutLog: runtimeLogPath("orchestrator-watch.out.log"),
+        stderrLog: runtimeLogPath("orchestrator-watch.err.log"),
+        linuxUnit: "you-orchestrator-watch.timer",
     },
 ];
+/**
+ * Which resident-daemon supervisor this host uses.
+ * - macOS → launchd (LaunchAgents), the original path.
+ * - Linux with a reachable `systemctl --user` → systemd user units (VPS path).
+ * - anything else → unsupported (sync still works on an interval via cron/manual).
+ */
+function detectDaemonBackend() {
+    if (process.platform === "darwin")
+        return "launchd";
+    if (process.platform === "linux" && hasUserSystemd())
+        return "systemd";
+    return "unsupported";
+}
+let cachedUserSystemd;
+function hasUserSystemd() {
+    // Only memoize a POSITIVE result: a transient probe failure at boot (user bus not up yet right
+    // after linger/boot) must not wedge a long-lived daemon into "no systemd" for its whole life.
+    if (cachedUserSystemd === true)
+        return true;
+    if (process.platform !== "linux")
+        return false;
+    // `--version` succeeds even with no user manager / no XDG_RUNTIME_DIR, so it is a poor proxy for
+    // "user units actually work" on a headless box. `show-environment` requires a live connection to
+    // the per-user systemd manager, which is exactly what enable/start/is-active need.
+    const result = child_process.spawnSync("systemctl", ["--user", "show-environment"], {
+        encoding: "utf-8",
+    });
+    const ok = !result.error && result.status === 0;
+    if (ok)
+        cachedUserSystemd = true;
+    return ok;
+}
 function expandHome(input) {
     if (input === "~")
         return os.homedir();
@@ -155,6 +204,28 @@ function isLaunchAgentLoaded(label) {
     });
     return result.status === 0 && !!result.stdout.trim();
 }
+/** True if the given systemd --user unit is active (running service or armed timer). */
+function isSystemdUnitActive(unit) {
+    if (!hasUserSystemd())
+        return false;
+    const result = child_process.spawnSync("systemctl", ["--user", "is-active", unit], {
+        encoding: "utf-8",
+    });
+    // `is-active` prints "active" / "activating" and exits 0 when up; non-zero otherwise.
+    const state = (result.stdout || "").trim();
+    return result.status === 0 && (state === "active" || state === "activating");
+}
+/** Platform-aware "is this daemon loaded?" for a YoumdDaemon, across launchd + systemd. */
+function isDaemonLoaded(daemon) {
+    switch (detectDaemonBackend()) {
+        case "launchd":
+            return isLaunchAgentLoaded(daemon.label);
+        case "systemd":
+            return isSystemdUnitActive(daemon.linuxUnit);
+        default:
+            return false;
+    }
+}
 function getDaemonHealth() {
     return exports.YOUMD_DAEMONS.map((daemon) => {
         const logs = [
@@ -172,7 +243,7 @@ function getDaemonHealth() {
             : undefined;
         return {
             ...daemon,
-            loaded: isLaunchAgentLoaded(daemon.label),
+            loaded: isDaemonLoaded(daemon),
             legacyLoaded: daemon.legacyLabel ? isLaunchAgentLoaded(daemon.legacyLabel) : false,
             lastLogLine: tailUsefulLine(daemon.combinedLog ?? daemon.stdoutLog) ?? tailUsefulLine(daemon.stdoutLog),
             lastErrorLine,

package/dist/lib/daemon.js.map

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

package/dist/lib/foldermd.d.ts

@@ -0,0 +1,70 @@
+export declare const FOLDERMD_DEFAULT_BASE = "https://www.folder.md/api/v1";
+export interface FolderMdAuth {
+    apiKey: string;
+    baseUrl?: string;
+}
+export interface FolderMdFile {
+    id: string;
+    path?: string;
+    name?: string;
+    size?: number;
+    mimeType?: string;
+    [k: string]: unknown;
+}
+/** Resolve a folder.md API key from explicit arg → config → env. Returns null if none. */
+export declare function resolveFolderMdKey(explicit?: string): string | null;
+/**
+ * Resolve a usable folder.md key with ZERO user paste. Explicit/env/config key
+ * wins; otherwise auto-provision via the you.md backend (mints a scoped key
+ * server-to-server) and cache it locally. Returns the key + the media folderId
+ * when provisioning supplied one. Throws a friendly error if not authenticated
+ * or if provisioning is not configured on the backend.
+ */
+export declare function ensureProvisionedKey(explicit?: string): Promise<{
+    apiKey: string;
+    folderId?: string;
+}>;
+/**
+ * Resolve the folder id to use for this user's media, creating + persisting a dedicated
+ * "you.md media" folder if none is configured. Shared by the CLI and the MCP tools so the
+ * "which folder?" logic lives in one place.
+ */
+export declare function ensureUserFolder(apiKey: string, explicit?: string): Promise<string>;
+/** List the user's folders (workspaces). */
+export declare function listFolders(auth: FolderMdAuth): Promise<unknown[]>;
+/** Create a folder (workspace), e.g. a per-you.md-user media folder. */
+export declare function createFolder(auth: FolderMdAuth, name: string): Promise<FolderMdFile>;
+/** List files in a folder. */
+export declare function listFiles(auth: FolderMdAuth, folderId: string): Promise<FolderMdFile[]>;
+/**
+ * Upload a local file (binary or text) to a folder via multipart. This is the large-file/media
+ * path the brain cannot handle. Returns the created file record (store its `id` as the brain
+ * pointer). For text-only content the folder.md MCP `file_write` tool is an alternative.
+ */
+export declare function uploadFile(auth: FolderMdAuth, folderId: string, localPath: string, options?: {
+    destPath?: string;
+    mimeType?: string;
+}): Promise<FolderMdFile>;
+/**
+ * Download a file's bytes. folder.md storage is private (no public CDN URL yet), so bytes come
+ * back through the authenticated API; you.md proxies/streams them rather than handing out a URL.
+ */
+export declare function downloadFile(auth: FolderMdAuth, folderId: string, fileId: string, destPath: string): Promise<{
+    bytes: number;
+    path: string;
+}>;
+/**
+ * The brain pointer: what you.md stores (as a plain string, which the bundle handles perfectly)
+ * to reference a media artifact living in folder.md. Embed JSON.stringify(this) in a memory or
+ * custom_file. No bytes ever enter the brain.
+ */
+export interface BrainMediaPointer {
+    provider: "folder.md";
+    folderId: string;
+    fileId: string;
+    name: string;
+    mimeType?: string;
+    size?: number;
+    uploadedAt: string;
+}
+//# sourceMappingURL=foldermd.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"foldermd.d.ts","sourceRoot":"","sources":["../../src/lib/foldermd.ts"],"names":[],"mappings":"AAkBA,eAAO,MAAM,qBAAqB,iCAAiC,CAAC;AAEpE,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CACtB;AAED,0FAA0F;AAC1F,wBAAgB,kBAAkB,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAUnE;AAED;;;;;;GAMG;AACH,wBAAsB,oBAAoB,CACxC,QAAQ,CAAC,EAAE,MAAM,GAChB,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAwBhD;AAoBD;;;;GAIG;AACH,wBAAsB,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAgBzF;AAWD,4CAA4C;AAC5C,wBAAsB,WAAW,CAAC,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC,CAQxE;AAED,wEAAwE;AACxE,wBAAsB,YAAY,CAAC,IAAI,EAAE,YAAY,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAS1F;AAED,8BAA8B;AAC9B,wBAAsB,SAAS,CAAC,IAAI,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAQ7F;AAED;;;;GAIG;AACH,wBAAsB,UAAU,CAC9B,IAAI,EAAE,YAAY,EAClB,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,OAAO,GAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAO,GACrD,OAAO,CAAC,YAAY,CAAC,CAiBvB;AAED;;;GAGG;AACH,wBAAsB,YAAY,CAChC,IAAI,EAAE,YAAY,EAClB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CAQ1C;AAED;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,WAAW,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;CACpB"}

package/dist/lib/foldermd.js

@@ -0,0 +1,226 @@
+"use strict";
+// foldermd.ts — You.md ↔ folder.md client (large-file / media offload).
+//
+// You.md is a structured-TEXT brain: every "file" is a markdown/JSON string in a ~1MB Convex
+// bundle, mirrored to GitHub under a 700KB text-only cap. There is NO binary/large-file path.
+// folder.md (Houston's own agent-native storage product) fills that slot. The brain stays
+// text-first and stores only a POINTER (folder.md folder/file id); the bytes live in folder.md.
+//
+// Auth is a per-folder Bearer API key (`fmd_live_…`). ZERO-USER-WORK provisioning now exists:
+// `ensureProvisionedKey()` calls the you.md backend (`POST /api/v1/me/storage/provision`),
+// which mints a scoped folder.md key server-to-server (shared FOLDERMD_SERVICE_SECRET) and
+// returns it to the authenticated owner's client, cached locally. The user never pastes a key.
+// An explicit key (config / FOLDER_API_KEY / FOLDERMD_API_KEY) still wins when present.
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FOLDERMD_DEFAULT_BASE = void 0;
+exports.resolveFolderMdKey = resolveFolderMdKey;
+exports.ensureProvisionedKey = ensureProvisionedKey;
+exports.ensureUserFolder = ensureUserFolder;
+exports.listFolders = listFolders;
+exports.createFolder = createFolder;
+exports.listFiles = listFiles;
+exports.uploadFile = uploadFile;
+exports.downloadFile = downloadFile;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const config_1 = require("./config");
+const api_1 = require("./api");
+exports.FOLDERMD_DEFAULT_BASE = "https://www.folder.md/api/v1";
+/** Resolve a folder.md API key from explicit arg → config → env. Returns null if none. */
+function resolveFolderMdKey(explicit) {
+    if (explicit && explicit.trim())
+        return explicit.trim();
+    const cfg = (0, config_1.readGlobalConfig)();
+    const fromCfg = typeof cfg.folderMdKey === "string" ? cfg.folderMdKey : undefined;
+    return (fromCfg ||
+        process.env.FOLDER_API_KEY ||
+        process.env.FOLDERMD_API_KEY ||
+        null);
+}
+/**
+ * Resolve a usable folder.md key with ZERO user paste. Explicit/env/config key
+ * wins; otherwise auto-provision via the you.md backend (mints a scoped key
+ * server-to-server) and cache it locally. Returns the key + the media folderId
+ * when provisioning supplied one. Throws a friendly error if not authenticated
+ * or if provisioning is not configured on the backend.
+ */
+async function ensureProvisionedKey(explicit) {
+    const local = resolveFolderMdKey(explicit);
+    if (local) {
+        const cfg = (0, config_1.readGlobalConfig)();
+        return { apiKey: local, folderId: cfg.folderMdFolderId };
+    }
+    const res = await (0, api_1.provisionStorage)();
+    if (!res.ok || !res.data?.apiKey) {
+        const msg = (0, api_1.apiErrorMessage)(res.data) ||
+            (res.status === 401
+                ? "not authenticated — run `you login` first"
+                : res.status === 503
+                    ? "folder.md storage isn't enabled on the server yet"
+                    : "could not provision folder.md storage");
+        throw new Error(msg);
+    }
+    const cfg = (0, config_1.readGlobalConfig)();
+    cfg.folderMdKey = res.data.apiKey;
+    if (res.data.folderId)
+        cfg.folderMdFolderId = res.data.folderId;
+    (0, config_1.writeGlobalConfig)(cfg);
+    return { apiKey: res.data.apiKey, folderId: res.data.folderId || cfg.folderMdFolderId };
+}
+function baseUrl(auth) {
+    return (auth.baseUrl || process.env.FOLDERMD_BASE_URL || exports.FOLDERMD_DEFAULT_BASE).replace(/\/$/, "");
+}
+function authHeaders(auth) {
+    return { Authorization: `Bearer ${auth.apiKey}` };
+}
+async function asError(res) {
+    let body = "";
+    try {
+        body = await res.text();
+    }
+    catch {
+        /* ignore */
+    }
+    return new Error(`folder.md ${res.status} ${res.statusText}${body ? `: ${body.slice(0, 300)}` : ""}`);
+}
+/**
+ * Resolve the folder id to use for this user's media, creating + persisting a dedicated
+ * "you.md media" folder if none is configured. Shared by the CLI and the MCP tools so the
+ * "which folder?" logic lives in one place.
+ */
+async function ensureUserFolder(apiKey, explicit) {
+    const cfg = (0, config_1.readGlobalConfig)();
+    const existing = (explicit && explicit.trim()) || cfg.folderMdFolderId;
+    if (existing)
+        return existing;
+    const auth = { apiKey };
+    // Reuse an existing folder if present, else create one.
+    try {
+        const folders = (await listFolders(auth));
+        const mine = folders.find((f) => f.name === "you.md media") || folders[0];
+        if (mine?.id)
+            return persistFolderId(mine.id);
+    }
+    catch {
+        // listing failed — fall through to create
+    }
+    const created = await createFolder(auth, "you.md media");
+    if (!created.id)
+        throw new Error("folder.md did not return a folder id on create");
+    return persistFolderId(String(created.id));
+}
+function persistFolderId(id) {
+    const cfg = (0, config_1.readGlobalConfig)();
+    if (cfg.folderMdFolderId !== id) {
+        cfg.folderMdFolderId = id;
+        (0, config_1.writeGlobalConfig)(cfg);
+    }
+    return id;
+}
+/** List the user's folders (workspaces). */
+async function listFolders(auth) {
+    const res = await fetch(`${baseUrl(auth)}/folders`, {
+        headers: authHeaders(auth),
+        signal: AbortSignal.timeout(30000),
+    });
+    if (!res.ok)
+        throw await asError(res);
+    const data = (await res.json());
+    return Array.isArray(data) ? data : data.folders ?? [];
+}
+/** Create a folder (workspace), e.g. a per-you.md-user media folder. */
+async function createFolder(auth, name) {
+    const res = await fetch(`${baseUrl(auth)}/folders`, {
+        method: "POST",
+        headers: { ...authHeaders(auth), "Content-Type": "application/json" },
+        body: JSON.stringify({ name }),
+        signal: AbortSignal.timeout(30000),
+    });
+    if (!res.ok)
+        throw await asError(res);
+    return (await res.json());
+}
+/** List files in a folder. */
+async function listFiles(auth, folderId) {
+    const res = await fetch(`${baseUrl(auth)}/folders/${encodeURIComponent(folderId)}/files`, {
+        headers: authHeaders(auth),
+        signal: AbortSignal.timeout(30000),
+    });
+    if (!res.ok)
+        throw await asError(res);
+    const data = (await res.json());
+    return Array.isArray(data) ? data : data.files ?? [];
+}
+/**
+ * Upload a local file (binary or text) to a folder via multipart. This is the large-file/media
+ * path the brain cannot handle. Returns the created file record (store its `id` as the brain
+ * pointer). For text-only content the folder.md MCP `file_write` tool is an alternative.
+ */
+async function uploadFile(auth, folderId, localPath, options = {}) {
+    if (!fs.existsSync(localPath))
+        throw new Error(`file not found: ${localPath}`);
+    const bytes = fs.readFileSync(localPath);
+    const name = options.destPath || path.basename(localPath);
+    const blob = new Blob([bytes], options.mimeType ? { type: options.mimeType } : undefined);
+    const form = new FormData();
+    form.append("file", blob, name);
+    if (options.destPath)
+        form.append("path", options.destPath);
+    const res = await fetch(`${baseUrl(auth)}/folders/${encodeURIComponent(folderId)}/files`, {
+        method: "POST",
+        headers: authHeaders(auth), // do NOT set Content-Type; fetch sets the multipart boundary
+        body: form,
+        signal: AbortSignal.timeout(120000),
+    });
+    if (!res.ok)
+        throw await asError(res);
+    return (await res.json());
+}
+/**
+ * Download a file's bytes. folder.md storage is private (no public CDN URL yet), so bytes come
+ * back through the authenticated API; you.md proxies/streams them rather than handing out a URL.
+ */
+async function downloadFile(auth, folderId, fileId, destPath) {
+    const url = `${baseUrl(auth)}/folders/${encodeURIComponent(folderId)}/files/${encodeURIComponent(fileId)}?download=true`;
+    const res = await fetch(url, { headers: authHeaders(auth), signal: AbortSignal.timeout(120000) });
+    if (!res.ok)
+        throw await asError(res);
+    const buf = Buffer.from(await res.arrayBuffer());
+    fs.mkdirSync(path.dirname(path.resolve(destPath)), { recursive: true });
+    fs.writeFileSync(destPath, buf);
+    return { bytes: buf.length, path: destPath };
+}
+//# sourceMappingURL=foldermd.js.map

package/dist/lib/foldermd.js.map

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

package/dist/lib/orchestrator/loop.d.ts

@@ -0,0 +1,55 @@
+export interface LoopTool {
+    name: string;
+    description: string;
+    /** Human-readable parameter hints, e.g. { harness: "claude|codex|cursor", goal: "task text" }. */
+    parameters: Record<string, string>;
+    run: (args: Record<string, unknown>) => Promise<string>;
+}
+export interface LoopMessage {
+    role: "system" | "user" | "assistant";
+    content: string;
+}
+/** Injected model caller — returns the assistant's raw text for a message list. */
+export type ModelCaller = (messages: LoopMessage[]) => Promise<string>;
+export interface LoopStep {
+    index: number;
+    tool: string;
+    args: Record<string, unknown>;
+    result: string;
+    thought?: string;
+}
+export interface RunLoopOptions {
+    goal: string;
+    tools: LoopTool[];
+    callModel: ModelCaller;
+    maxSteps?: number;
+    /** Extra orientation injected into the system prompt (identity, machine, fleet state). */
+    context?: string;
+    /** Progress callback per step (for spinner/log output). */
+    onStep?: (step: LoopStep) => void;
+    /**
+     * Transient model-call failures to absorb before giving up on a step (real LLM APIs hiccup;
+     * one network blip shouldn't abandon the whole goal). Default 2 retries → 3 attempts total.
+     */
+    maxModelRetries?: number;
+    /** Injectable sleep (so tests don't wait on real backoff). Defaults to setTimeout. */
+    sleep?: (ms: number) => Promise<void>;
+}
+export interface LoopOutcome {
+    finished: boolean;
+    summary: string;
+    steps: LoopStep[];
+}
+interface ToolCall {
+    thought?: string;
+    tool: string;
+    args: Record<string, unknown>;
+}
+export declare function parseToolCall(raw: string): ToolCall | null;
+/**
+ * Run the orchestrator loop until the model calls `finish` or maxSteps is hit.
+ * Each step: ask the model for a tool call → run it → append the result → repeat.
+ */
+export declare function runAgentLoop(options: RunLoopOptions): Promise<LoopOutcome>;
+export {};
+//# sourceMappingURL=loop.d.ts.map

package/dist/lib/orchestrator/loop.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loop.d.ts","sourceRoot":"","sources":["../../../src/lib/orchestrator/loop.ts"],"names":[],"mappings":"AAaA,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,kGAAkG;IAClG,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACnC,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;CACzD;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,QAAQ,GAAG,MAAM,GAAG,WAAW,CAAC;IACtC,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,mFAAmF;AACnF,MAAM,MAAM,WAAW,GAAG,CAAC,QAAQ,EAAE,WAAW,EAAE,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;AAEvE,MAAM,WAAW,QAAQ;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,QAAQ,EAAE,CAAC;IAClB,SAAS,EAAE,WAAW,CAAC;IACvB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,0FAA0F;IAC1F,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,2DAA2D;IAC3D,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,QAAQ,KAAK,IAAI,CAAC;IAClC;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,sFAAsF;IACtF,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACvC;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,OAAO,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,QAAQ,EAAE,CAAC;CACnB;AAED,UAAU,QAAQ;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/B;AAyDD,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,QAAQ,GAAG,IAAI,CAwD1D;AAMD;;;GAGG;AACH,wBAAsB,YAAY,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,WAAW,CAAC,CAkHhF"}