instar 0.28.82 → 0.28.84

package/dist/tasks/task-flow-types.js

@@ -0,0 +1,128 @@
+/**
+ * TaskFlow — types and constants.
+ *
+ * Imported from OpenClaw's task-flow-registry shape, trimmed for Instar v1
+ * (single-writer; managed-only; no `blocked` status).
+ *
+ * See docs/specs/OPENCLAW-IMPORT-TASKFLOW-SPEC.md for full design.
+ */
+import { z } from 'zod';
+export const TERMINAL_STATUSES = new Set([
+    'succeeded',
+    'failed',
+    'cancelled',
+    'lost',
+]);
+// ---------- size limits ----------
+export const MAX_OWNER_KEY_CHARS = 256;
+export const MAX_GOAL_CHARS = 1024;
+export const MAX_CURRENT_STEP_CHARS = 128;
+export const MAX_STATE_JSON_BYTES = 64 * 1024;
+export const MAX_WAIT_JSON_BYTES = 8 * 1024;
+// ---------- defaults ----------
+export const DEFAULT_THRESHOLDS = {
+    RUNNING_LOST_MS: 6 * 60 * 60 * 1000, // 6h
+    REPLY_LOST_MS: 7 * 24 * 60 * 60 * 1000, // 7d
+    HUMAN_REVIEW_LOST_MS: 30 * 24 * 60 * 60 * 1000, // 30d
+    EXTERNAL_LOST_MS: 7 * 24 * 60 * 60 * 1000, // 7d
+    EXTERNAL_GRACE_MS: 60 * 60 * 1000, // 1h
+    XAGENT_LOST_MS: 7 * 24 * 60 * 60 * 1000, // 7d
+};
+export const HEARTBEAT_INTERVAL_MS = 60 * 1000;
+export const SWEEPER_INTERVAL_MS = 60 * 60 * 1000; // hourly
+export const DUE_WAKER_INTERVAL_MS = 60 * 1000; // every minute
+export const MAX_CACHE_ENTRIES = 1000;
+export const MAX_BUSY_RETRIES = 5;
+export const BUSY_BASE_DELAY_MS = 50;
+export const BUSY_CAP_DELAY_MS = 5000;
+export const RESERVED_MAINTENANCE_CONTROLLER = 'TaskFlowMaintenance';
+// ---------- Phase 5: rate limits + cache cap defaults ----------
+// Spec § Threat Model lines 679, 685; § Phase 5 line 650-653.
+export const DEFAULT_CREATE_PER_SEC_PER_CONTROLLER = 10;
+export const DEFAULT_MAX_ACTIVE_PER_CONTROLLER = 50;
+export const DEFAULT_PING_PER_MIN_PER_FLOW = 60;
+export const DEFAULT_CACHE_MAX_ENTRIES = MAX_CACHE_ENTRIES;
+export const DEFAULT_RATE_LIMITS = {
+    createPerSecPerController: DEFAULT_CREATE_PER_SEC_PER_CONTROLLER,
+    maxActivePerController: DEFAULT_MAX_ACTIVE_PER_CONTROLLER,
+    pingPerMinPerFlow: DEFAULT_PING_PER_MIN_PER_FLOW,
+};
+export const DEFAULT_CACHE_CONFIG = {
+    maxEntries: DEFAULT_CACHE_MAX_ENTRIES,
+};
+/** Active (non-terminal) flow statuses for max-active-per-controller bookkeeping. */
+export const ACTIVE_STATUSES = ['queued', 'running', 'waiting'];
+export class TaskFlowError extends Error {
+    code;
+    detail;
+    constructor(code, message, detail = {}) {
+        super(message);
+        this.name = 'TaskFlowError';
+        this.code = code;
+        this.detail = detail;
+    }
+}
+// ---------- zod schemas ----------
+const requesterOriginSchema = z.object({
+    kind: z.enum(['user', 'agent', 'system', 'job']),
+    id: z.string().min(1).max(256),
+    channel: z.string().max(256).optional(),
+});
+const notifyPolicySchema = z.discriminatedUnion('kind', [
+    z.object({ kind: z.literal('silent') }),
+    z.object({ kind: z.literal('on-wait'), topicId: z.number().int() }),
+    z.object({ kind: z.literal('on-terminal'), topicId: z.number().int() }),
+    z.object({ kind: z.literal('on-wait-and-terminal'), topicId: z.number().int() }),
+]);
+export const waitJsonSchema = z.discriminatedUnion('kind', [
+    z.object({
+        kind: z.literal('reply'),
+        channel: z.string().min(1).max(256),
+        threadId: z.string().min(1).max(256),
+        peer: z.string().min(1).max(256),
+    }),
+    z.object({
+        kind: z.literal('human-review'),
+        question: z.string().min(1).max(2000),
+        topicId: z.number().int().optional(),
+        reviewerId: z.string().max(256).optional(),
+    }),
+    z.object({
+        kind: z.literal('external-call'),
+        serviceId: z.string().min(1).max(256),
+        correlationId: z.string().min(16).max(256),
+        deadline: z.number().int().optional(),
+    }),
+    z.object({
+        kind: z.literal('scheduled-tick'),
+        dueAt: z.number().int(),
+        jobSlug: z.string().max(256).optional(),
+    }),
+    z.object({
+        kind: z.literal('cross-agent-callback'),
+        threadId: z.string().min(1).max(256),
+        correlationId: z.string().min(16).max(256),
+        expectedAgentId: z.string().min(1).max(256),
+    }),
+]);
+export const createFlowInputSchema = z.object({
+    ownerKey: z.string().min(1).max(MAX_OWNER_KEY_CHARS),
+    controllerId: z.string().min(1).max(256),
+    controllerInstanceId: z.string().min(1).max(256),
+    idempotencyKey: z.string().min(8).max(256),
+    goal: z.string().min(1).max(MAX_GOAL_CHARS),
+    currentStep: z.string().max(MAX_CURRENT_STEP_CHARS).optional(),
+    stateJson: z.unknown().optional(),
+    notifyPolicy: notifyPolicySchema.optional(),
+    requesterOrigin: requesterOriginSchema.optional(),
+    privacyScope: z.enum(['private', 'shared-topic', 'shared-project']).optional(),
+});
+export function jsonByteLength(value) {
+    if (value === undefined)
+        return 0;
+    return Buffer.byteLength(JSON.stringify(value), 'utf8');
+}
+export function isTerminalStatus(status) {
+    return TERMINAL_STATUSES.has(status);
+}
+//# sourceMappingURL=task-flow-types.js.map

package/dist/tasks/task-flow-types.js.map

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

package/dist/threadline/ThreadlineNicknames.d.ts

@@ -0,0 +1,88 @@
+/**
+ * ThreadlineNicknames — user-editable display names for threadline agents,
+ * keyed by fingerprint (or any stable id).
+ *
+ * Storage: .instar/threadline/nicknames.json
+ *   {
+ *     "version": 1,
+ *     "nicknames": {
+ *       "8c7928aa9f04fbda...": {
+ *         "nickname": "Dawn",
+ *         "source": "user" | "haiku" | "import",
+ *         "updatedAt": "2026-05-06T17:00:00.000Z"
+ *       }
+ *     }
+ *   }
+ */
+export type NicknameSource = 'user' | 'haiku' | 'import';
+export interface NicknameEntry {
+    nickname: string;
+    source: NicknameSource;
+    updatedAt: string;
+}
+export interface ThreadlineNicknamesOptions {
+    stateDir: string;
+}
+export declare class ThreadlineNicknames {
+    private readonly stateDir;
+    private cache;
+    private cacheReadAt;
+    private static readonly CACHE_TTL_MS;
+    constructor(opts: ThreadlineNicknamesOptions);
+    /** Path to the nicknames JSON file. */
+    filePath(): string;
+    /** Returns the nickname for a fingerprint, or null if none set. */
+    get(fingerprint: string): NicknameEntry | null;
+    /** Returns all nicknames as a plain map. */
+    all(): Record<string, NicknameEntry>;
+    /**
+     * Canonicalize a name for authority-grade comparison.
+     *
+     * Applies Unicode NFC normalization, trims surrounding whitespace,
+     * collapses internal whitespace runs to a single space, and lowercases.
+     * This is what makes two visually-identical names compare equal even
+     * when one was hand-edited with stray whitespace, mixed case, or
+     * combining-character forms.
+     *
+     * Used by `resolveByName()` on BOTH the lookup key AND each stored
+     * entry's nickname at compare time — so we never mutate the user's
+     * chosen display string on disk (preserving their preferred casing
+     * and spacing for the dashboard), but lookups still match across
+     * cosmetic differences. `set()` does NOT pre-canonicalize on store
+     * for the same reason: the stored string is user-presentation; the
+     * canonical form is comparison-only.
+     */
+    static canonicalizeName(name: string): string;
+    /**
+     * Reverse-lookup: nickname → fingerprint. Canonicalized exact match
+     * (NFC-normalized, internal-whitespace-collapsed, case-insensitive).
+     *
+     * Returns null if no nickname matches. If multiple fingerprints share
+     * the same nickname (rare; user shouldn't do this but the file allows it),
+     * returns { ambiguous: true, candidates: [...] } so callers can fail
+     * loudly instead of silently picking one.
+     *
+     * The send-path resolver consults this BEFORE relay discovery so that
+     * user-curated names take authority over potentially-stale or imposter
+     * presence entries. See routes.ts /threadline/relay-send.
+     */
+    resolveByName(name: string): {
+        fingerprint: string;
+        entry: NicknameEntry;
+    } | {
+        ambiguous: true;
+        candidates: Array<{
+            fingerprint: string;
+            entry: NicknameEntry;
+        }>;
+    } | null;
+    /** Set a nickname for a fingerprint. Empty/whitespace nickname clears it. */
+    set(fingerprint: string, nickname: string, source?: NicknameSource): NicknameEntry | null;
+    /** Delete a nickname mapping. Returns true if one existed. */
+    delete(fingerprint: string): boolean;
+    /** Force-reload on next get(). */
+    invalidate(): void;
+    private load;
+    private persist;
+}
+//# sourceMappingURL=ThreadlineNicknames.d.ts.map

package/dist/threadline/ThreadlineNicknames.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ThreadlineNicknames.d.ts","sourceRoot":"","sources":["../../src/threadline/ThreadlineNicknames.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAKH,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,CAAC;AAEzD,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,cAAc,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;CACnB;AAOD,MAAM,WAAW,0BAA0B;IACzC,QAAQ,EAAE,MAAM,CAAC;CAClB;AAID,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,KAAK,CAA2C;IACxD,OAAO,CAAC,WAAW,CAAK;IACxB,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,YAAY,CAAU;gBAElC,IAAI,EAAE,0BAA0B;IAI5C,uCAAuC;IACvC,QAAQ,IAAI,MAAM;IAIlB,mEAAmE;IACnE,GAAG,CAAC,WAAW,EAAE,MAAM,GAAG,aAAa,GAAG,IAAI;IAM9C,4CAA4C;IAC5C,GAAG,IAAI,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC;IAOpC;;;;;;;;;;;;;;;;OAgBG;IACH,MAAM,CAAC,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IAS7C;;;;;;;;;;;;OAYG;IACH,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,aAAa,CAAA;KAAE,GAAG;QAAE,SAAS,EAAE,IAAI,CAAC;QAAC,UAAU,EAAE,KAAK,CAAC;YAAE,WAAW,EAAE,MAAM,CAAC;YAAC,KAAK,EAAE,aAAa,CAAA;SAAE,CAAC,CAAA;KAAE,GAAG,IAAI;IAezK,6EAA6E;IAC7E,GAAG,CAAC,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,GAAE,cAAuB,GAAG,aAAa,GAAG,IAAI;IAsBjG,8DAA8D;IAC9D,MAAM,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO;IAQpC,kCAAkC;IAClC,UAAU,IAAI,IAAI;IAOlB,OAAO,CAAC,IAAI;IAqCZ,OAAO,CAAC,OAAO;CAiBhB"}

package/dist/threadline/ThreadlineNicknames.js

@@ -0,0 +1,195 @@
+/**
+ * ThreadlineNicknames — user-editable display names for threadline agents,
+ * keyed by fingerprint (or any stable id).
+ *
+ * Storage: .instar/threadline/nicknames.json
+ *   {
+ *     "version": 1,
+ *     "nicknames": {
+ *       "8c7928aa9f04fbda...": {
+ *         "nickname": "Dawn",
+ *         "source": "user" | "haiku" | "import",
+ *         "updatedAt": "2026-05-06T17:00:00.000Z"
+ *       }
+ *     }
+ *   }
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+const FILE_VERSION = 1;
+export class ThreadlineNicknames {
+    stateDir;
+    cache = null;
+    cacheReadAt = 0;
+    static CACHE_TTL_MS = 30_000;
+    constructor(opts) {
+        this.stateDir = opts.stateDir;
+    }
+    /** Path to the nicknames JSON file. */
+    filePath() {
+        return path.join(this.stateDir, 'threadline', 'nicknames.json');
+    }
+    /** Returns the nickname for a fingerprint, or null if none set. */
+    get(fingerprint) {
+        if (!fingerprint)
+            return null;
+        const map = this.load();
+        return map.get(fingerprint) ?? null;
+    }
+    /** Returns all nicknames as a plain map. */
+    all() {
+        const map = this.load();
+        const out = {};
+        for (const [k, v] of map)
+            out[k] = v;
+        return out;
+    }
+    /**
+     * Canonicalize a name for authority-grade comparison.
+     *
+     * Applies Unicode NFC normalization, trims surrounding whitespace,
+     * collapses internal whitespace runs to a single space, and lowercases.
+     * This is what makes two visually-identical names compare equal even
+     * when one was hand-edited with stray whitespace, mixed case, or
+     * combining-character forms.
+     *
+     * Used by `resolveByName()` on BOTH the lookup key AND each stored
+     * entry's nickname at compare time — so we never mutate the user's
+     * chosen display string on disk (preserving their preferred casing
+     * and spacing for the dashboard), but lookups still match across
+     * cosmetic differences. `set()` does NOT pre-canonicalize on store
+     * for the same reason: the stored string is user-presentation; the
+     * canonical form is comparison-only.
+     */
+    static canonicalizeName(name) {
+        if (!name)
+            return '';
+        return name
+            .normalize('NFC')
+            .trim()
+            .replace(/\s+/g, ' ')
+            .toLowerCase();
+    }
+    /**
+     * Reverse-lookup: nickname → fingerprint. Canonicalized exact match
+     * (NFC-normalized, internal-whitespace-collapsed, case-insensitive).
+     *
+     * Returns null if no nickname matches. If multiple fingerprints share
+     * the same nickname (rare; user shouldn't do this but the file allows it),
+     * returns { ambiguous: true, candidates: [...] } so callers can fail
+     * loudly instead of silently picking one.
+     *
+     * The send-path resolver consults this BEFORE relay discovery so that
+     * user-curated names take authority over potentially-stale or imposter
+     * presence entries. See routes.ts /threadline/relay-send.
+     */
+    resolveByName(name) {
+        const canonical = ThreadlineNicknames.canonicalizeName(name);
+        if (!canonical)
+            return null;
+        const map = this.load();
+        const matches = [];
+        for (const [fp, entry] of map) {
+            if (ThreadlineNicknames.canonicalizeName(entry.nickname) === canonical) {
+                matches.push({ fingerprint: fp, entry });
+            }
+        }
+        if (matches.length === 0)
+            return null;
+        if (matches.length === 1)
+            return matches[0];
+        return { ambiguous: true, candidates: matches };
+    }
+    /** Set a nickname for a fingerprint. Empty/whitespace nickname clears it. */
+    set(fingerprint, nickname, source = 'user') {
+        if (!fingerprint)
+            throw new Error('fingerprint required');
+        const trimmed = nickname.trim();
+        const map = this.load();
+        if (trimmed.length === 0) {
+            map.delete(fingerprint);
+            this.persist(map);
+            return null;
+        }
+        if (trimmed.length > 64) {
+            throw new Error('nickname too long (max 64 chars)');
+        }
+        const entry = {
+            nickname: trimmed,
+            source,
+            updatedAt: new Date().toISOString(),
+        };
+        map.set(fingerprint, entry);
+        this.persist(map);
+        return entry;
+    }
+    /** Delete a nickname mapping. Returns true if one existed. */
+    delete(fingerprint) {
+        const map = this.load();
+        if (!map.has(fingerprint))
+            return false;
+        map.delete(fingerprint);
+        this.persist(map);
+        return true;
+    }
+    /** Force-reload on next get(). */
+    invalidate() {
+        this.cache = null;
+        this.cacheReadAt = 0;
+    }
+    // ── internal ───────────────────────────────────────────────────
+    load() {
+        const fresh = Date.now() - this.cacheReadAt < ThreadlineNicknames.CACHE_TTL_MS;
+        if (this.cache && fresh)
+            return this.cache;
+        const map = new Map();
+        const file = this.filePath();
+        if (fs.existsSync(file)) {
+            try {
+                const raw = fs.readFileSync(file, 'utf-8');
+                const parsed = JSON.parse(raw);
+                const items = parsed?.nicknames ?? {};
+                for (const [k, v] of Object.entries(items)) {
+                    if (v && typeof v.nickname === 'string') {
+                        map.set(k, {
+                            nickname: v.nickname,
+                            source: v.source ?? 'user',
+                            updatedAt: v.updatedAt ?? new Date().toISOString(),
+                        });
+                    }
+                }
+            }
+            catch (err) {
+                // Corrupt file — degrade to empty map (sends still flow via
+                // relay-discovery fallback) but make the silent authority loss
+                // visible. One log per cache cycle (every 30s at most), so a
+                // persistently-corrupt file doesn't spam logs but is observable.
+                const msg = err instanceof Error ? err.message : String(err);
+                console.warn(`[ThreadlineNicknames] nicknames.json parse failed at ${file}: ${msg}. ` +
+                    `Treating as empty (no user-curated authority for this load cycle). ` +
+                    `Outbound sends will fall back to relay-discovery for nicknamed names.`);
+            }
+        }
+        this.cache = map;
+        this.cacheReadAt = Date.now();
+        return map;
+    }
+    persist(map) {
+        const file = this.filePath();
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        const obj = {
+            version: FILE_VERSION,
+            nicknames: Object.fromEntries(map),
+        };
+        // Atomic write: temp + rename. Prevents a concurrent reader from
+        // observing a half-written file (which would parse-fail and degrade
+        // to "no nicknames" — silent authority loss). rename(2) is atomic on
+        // POSIX when source and destination live on the same filesystem.
+        const tmp = `${file}.tmp-${process.pid}-${Date.now()}`;
+        fs.writeFileSync(tmp, JSON.stringify(obj, null, 2), 'utf-8');
+        fs.renameSync(tmp, file);
+        this.cache = map;
+        this.cacheReadAt = Date.now();
+    }
+}
+//# sourceMappingURL=ThreadlineNicknames.js.map

package/dist/threadline/ThreadlineNicknames.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "0.28.82",
+  "version": "0.28.84",
   "description": "Persistent autonomy infrastructure for AI agents",
   "type": "module",
   "main": "dist/index.js",