crewly 1.20.143 → 1.20.144

package/dist/cli/backend/src/services/orc/orc-reply-route.service.js

@@ -0,0 +1,300 @@
+/**
+ * Orchestrator reply routing — "answer where you were asked".
+ *
+ * Tracks, per agent session, the conversation its latest user-originated
+ * message came from (the *turn origin*), and decides where a reply the
+ * orchestrator posts during or right after that turn should land.
+ *
+ * Incident 2026-09-26 03:23–03:34 UTC: the owner was talking to the orc in a
+ * Slack DM (D0C381XPD3L → chat-v2 channel a721f48d). A reconciler WorkItem
+ * redispatch then started a system turn with no `[CHAT:…]` prefix. In it the
+ * orc:
+ *   - filed `report-status [BLOCKED]` and `reply-chat` without a
+ *     conversationId; `/api/chat/agent-response` fell back to
+ *     `ChatService.getCurrentConversation()`, which only sees system-owned
+ *     channels — never the owner's orchestrator DM — and returned #think-tank
+ *     (b79a6e4d), so the summary was mirrored into Slack #pro-think-tank;
+ *   - called `reply-slack` on D0AC7NF5N7L, the owner's DM with the *master*
+ *     Crewly bot, not the orc-bot DM the conversation was in.
+ * The question in that summary ("reply start Ella") never reached the owner.
+ *
+ * What counts as "the reply": anything the orchestrator posts to a
+ * user-facing conversation through `/api/chat/agent-response` (reply-chat,
+ * report-status) or to a Slack DM through `/api/slack/send` (reply-slack).
+ * It is re-routed to the turn origin when it targets a conversation the orc
+ * has not received a user message from recently, unless the caller marked it
+ * as a deliberate cross-post. Posts to Slack channels (team notifications,
+ * delegation) and `reply-channel` writes are not replies and are untouched.
+ *
+ * @module services/orc/orc-reply-route.service
+ */
+import { ORC_REPLY_ROUTE_CONSTANTS } from '../../constants.js';
+/**
+ * `[CHAT:<id>…]` / `[GCHAT:<id>…]` at the start of a delivered message. Both
+ * delivery paths put it first: the chat-v2 dispatcher (`[CHAT:<channel>]
+ * <sender@name>`) and the message queue (`[CHAT:<conversation>:<fp>] …`).
+ * System deliveries (`[SYSTEM]`, `[CREWLY-DISPATCH]`, reminders) never do.
+ */
+const CHAT_PREFIX = /^\s*\[G?CHAT:([^\]\s]+)[^\]]*\]/;
+/**
+ * The message queue appends `:<last 8 chars of the message id>` to the
+ * conversation id as a delivery fingerprint.
+ */
+const QUEUE_FINGERPRINT_SUFFIX = /^(.+):[A-Za-z0-9-]{8}$/;
+/** `[SLACK:<channel>]` or `[SLACK:<channel>:<threadTs>]`, anywhere. */
+const SLACK_MARKER = /\[SLACK:([^:\]\s]+)(?::([^\]\s]+))?\]/;
+/**
+ * Parses the routing header of a message delivered to an agent.
+ *
+ * @param message - The exact text delivered to the agent
+ * @returns The origin, or null for system-originated deliveries
+ *
+ * @example
+ * ```typescript
+ * parseInboundOrigin('[CHAT:a721f48d] <owner@Orchestrator>\n\nhi');
+ * // → { conversationId: 'a721f48d' }
+ * ```
+ */
+export function parseInboundOrigin(message) {
+    const chat = CHAT_PREFIX.exec(message);
+    if (!chat)
+        return null;
+    const raw = chat[1];
+    const fp = QUEUE_FINGERPRINT_SUFFIX.exec(raw);
+    const origin = { conversationId: fp ? fp[1] : raw };
+    const slack = SLACK_MARKER.exec(message);
+    if (slack) {
+        origin.slackChannelId = slack[1];
+        if (slack[2])
+            origin.slackThreadTs = slack[2];
+    }
+    return origin;
+}
+/**
+ * Whether a Slack channel id is a direct-message conversation.
+ *
+ * @param slackChannelId - Slack channel id
+ * @returns True for `D…` ids
+ */
+export function isSlackDm(slackChannelId) {
+    return slackChannelId.startsWith(ORC_REPLY_ROUTE_CONSTANTS.SLACK_DM_PREFIX);
+}
+/**
+ * Tracks turn origins and decides reply targets. Process-wide singleton; all
+ * state is in memory (a restart starts every agent on a fresh turn anyway).
+ */
+export class OrcReplyRouteService {
+    static instance = null;
+    sessions = new Map();
+    /**
+     * @returns The shared instance
+     */
+    static getInstance() {
+        if (!OrcReplyRouteService.instance)
+            OrcReplyRouteService.instance = new OrcReplyRouteService();
+        return OrcReplyRouteService.instance;
+    }
+    /** Drops the shared instance (tests). */
+    static resetInstance() {
+        OrcReplyRouteService.instance = null;
+    }
+    /**
+     * Records a message delivered to an agent. User-originated messages (those
+     * with a `[CHAT:…]` header) become the session's turn origin; system
+     * deliveries leave the origin alone, so a system turn that follows a user
+     * turn still answers the user where they asked.
+     *
+     * @param sessionName - Receiving agent session
+     * @param message - Exact delivered text
+     * @param now - Clock override for tests
+     * @returns The new origin, or null when the message was system-originated
+     */
+    noteDelivery(sessionName, message, now = Date.now()) {
+        const parsed = parseInboundOrigin(message);
+        if (!parsed)
+            return null;
+        const state = this.stateFor(sessionName);
+        const origin = { ...parsed, receivedAt: now };
+        state.origin = origin;
+        remember(state.conversations, origin.conversationId, now);
+        if (origin.slackChannelId)
+            remember(state.slackChannels, origin.slackChannelId, now);
+        return origin;
+    }
+    /**
+     * The session's turn origin, however old.
+     *
+     * @param sessionName - Agent session
+     * @returns The last user-originated origin, or undefined
+     */
+    getLastOrigin(sessionName) {
+        return this.sessions.get(sessionName)?.origin;
+    }
+    /**
+     * The session's turn origin if it is still fresh.
+     *
+     * @param sessionName - Agent session
+     * @param now - Clock override for tests
+     * @returns The origin within {@link ORC_REPLY_ROUTE_CONSTANTS.ORIGIN_TTL_MS}
+     */
+    getFreshOrigin(sessionName, now = Date.now()) {
+        const origin = this.getLastOrigin(sessionName);
+        if (!origin)
+            return undefined;
+        return now - origin.receivedAt <= ORC_REPLY_ROUTE_CONSTANTS.ORIGIN_TTL_MS ? origin : undefined;
+    }
+    /**
+     * Decides which conversation a chat reply (reply-chat, report-status)
+     * belongs in.
+     *
+     * - No conversation named → the turn origin (any age: it is still a better
+     *   guess than "the newest channel in the system"); none known → caller's
+     *   own fallback.
+     * - A conversation named → kept when it is the origin, when the session
+     *   received a user message there recently, when the caller marked a
+     *   cross-post, or when there is no fresh origin to prefer. Otherwise the
+     *   reply goes to the origin.
+     *
+     * @param sessionName - Replying agent session
+     * @param requested - Conversation the caller named, if any
+     * @param options - Cross-post flag and clock
+     * @returns The decision
+     */
+    resolveConversationReply(sessionName, requested, options = {}) {
+        const now = options.now ?? Date.now();
+        if (!requested) {
+            const last = this.getLastOrigin(sessionName);
+            return last
+                ? { action: 'defaulted-to-origin', conversationId: last.conversationId, origin: last, reason: 'no conversation named — using the conversation the turn came from' }
+                : { action: 'no-origin', reason: 'no conversation named and no turn origin known' };
+        }
+        const origin = this.getFreshOrigin(sessionName, now);
+        if (!origin)
+            return { action: 'as-requested', conversationId: requested, reason: 'no fresh turn origin' };
+        if (requested === origin.conversationId) {
+            return { action: 'as-requested', conversationId: requested, origin, reason: 'is the turn origin' };
+        }
+        if (options.crossPost) {
+            return { action: 'as-requested', conversationId: requested, origin, reason: 'explicit cross-post' };
+        }
+        if (this.receivedRecently(this.sessions.get(sessionName)?.conversations, requested, now)) {
+            return { action: 'as-requested', conversationId: requested, origin, reason: 'received a user message there recently' };
+        }
+        return {
+            action: 'rerouted-to-origin',
+            conversationId: origin.conversationId,
+            origin,
+            reason: 'named a conversation the turn did not come from and no user wrote in recently',
+        };
+    }
+    /**
+     * Decides whether a Slack post is a misdirected reply. Only DMs are
+     * candidates — posting in a channel is how the orchestrator notifies teams
+     * and delegates, so channel posts are always sent as asked.
+     *
+     * @param sessionName - Posting agent session
+     * @param slackChannelId - Slack channel the caller named
+     * @param options - Cross-post flag, clock, and the Slack DM the origin
+     *   conversation is bridged to (when the delivered message had no marker)
+     * @returns The decision
+     */
+    resolveSlackReply(sessionName, slackChannelId, options = {}) {
+        const now = options.now ?? Date.now();
+        if (!isSlackDm(slackChannelId)) {
+            return { action: 'as-requested', reason: 'channel post — cross-posting allowed' };
+        }
+        const origin = this.getFreshOrigin(sessionName, now);
+        if (!origin)
+            return { action: 'as-requested', reason: 'no fresh turn origin' };
+        const originSlack = origin.slackChannelId ?? options.originSlackChannelId;
+        if (originSlack === slackChannelId) {
+            return { action: 'as-requested', origin, reason: 'is the turn origin' };
+        }
+        if (options.crossPost)
+            return { action: 'as-requested', origin, reason: 'explicit cross-post' };
+        if (this.receivedRecently(this.sessions.get(sessionName)?.slackChannels, slackChannelId, now)) {
+            return { action: 'as-requested', origin, reason: 'received a user message there recently' };
+        }
+        return {
+            action: 'rerouted-to-origin',
+            origin,
+            reason: 'posted to a Slack DM the turn did not come from and no user wrote in recently',
+        };
+    }
+    /**
+     * Plans where a Slack post by `sessionName` should go.
+     *
+     * When {@link resolveSlackReply} re-routes, the destination is the origin's
+     * own Slack conversation if the delivered message carried a `[SLACK:…]`
+     * marker (the master-bot bridge), else the origin chat-v2 conversation —
+     * which the Slack DM bridge mirrors into the agent-bot DM the owner wrote
+     * in, under the right bot.
+     *
+     * @param sessionName - Posting agent session
+     * @param target - Slack channel/thread the caller named, and its cross-post flag
+     * @param findDmSlackChannel - Maps a chat-v2 conversation to the Slack DM it
+     *   is bridged to, when it is
+     * @param now - Clock override for tests
+     * @returns The plan and the decision behind it
+     */
+    planSlackReply(sessionName, target, findDmSlackChannel, now = Date.now()) {
+        const fresh = this.getFreshOrigin(sessionName, now);
+        const originSlackChannelId = fresh && !fresh.slackChannelId ? findDmSlackChannel(fresh.conversationId) : undefined;
+        const decision = this.resolveSlackReply(sessionName, target.channelId, {
+            crossPost: target.crossPost,
+            originSlackChannelId,
+            now,
+        });
+        if (decision.action !== 'rerouted-to-origin' || !decision.origin) {
+            return { plan: { kind: 'slack', channelId: target.channelId, threadTs: target.threadTs }, decision };
+        }
+        const origin = decision.origin;
+        const plan = origin.slackChannelId
+            ? { kind: 'slack', channelId: origin.slackChannelId, threadTs: origin.slackThreadTs }
+            : { kind: 'conversation', conversationId: origin.conversationId };
+        return { plan, decision };
+    }
+    /**
+     * Whether an inbound map saw `key` within the recent-inbound window.
+     *
+     * @param seen - Inbound map
+     * @param key - Conversation or Slack channel id
+     * @param now - Epoch ms
+     * @returns True when recent
+     */
+    receivedRecently(seen, key, now) {
+        const at = seen?.get(key);
+        return at !== undefined && now - at <= ORC_REPLY_ROUTE_CONSTANTS.RECENT_INBOUND_MS;
+    }
+    /**
+     * @param sessionName - Agent session
+     * @returns Its state, created on first use
+     */
+    stateFor(sessionName) {
+        let state = this.sessions.get(sessionName);
+        if (!state) {
+            state = { conversations: new Map(), slackChannels: new Map() };
+            this.sessions.set(sessionName, state);
+        }
+        return state;
+    }
+}
+/**
+ * Records `key` as seen at `at`, keeping the map bounded (oldest first out;
+ * Map preserves insertion order, and re-inserting moves a key to the end).
+ *
+ * @param map - Inbound map
+ * @param key - Conversation or Slack channel id
+ * @param at - Epoch ms
+ */
+function remember(map, key, at) {
+    map.delete(key);
+    map.set(key, at);
+    while (map.size > ORC_REPLY_ROUTE_CONSTANTS.MAX_TRACKED_CONVERSATIONS) {
+        const oldest = map.keys().next().value;
+        if (oldest === undefined)
+            break;
+        map.delete(oldest);
+    }
+}
+//# sourceMappingURL=orc-reply-route.service.js.map

package/dist/cli/backend/src/services/orc/orc-reply-route.service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"orc-reply-route.service.js","sourceRoot":"","sources":["../../../../../../backend/src/services/orc/orc-reply-route.service.ts"],"names":[],"mappings":"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"}

package/dist/cli/backend/src/services/system/auto-update.utils.d.ts

@@ -0,0 +1,265 @@
+/**
+ * Auto-update helpers — pure / filesystem-only pieces of the self-update
+ * (specs/auto-update.md), kept apart from the service so each rule is
+ * testable without timers:
+ *
+ * - where the running copy lives and what kind of install it is (npm global,
+ *   user-prefix npm, dev checkout, anything else);
+ * - the `npm install -g` arguments that target that same prefix;
+ * - the on/off decision (setting + env override);
+ * - whether a supervisor will bring the backend back after RESTART_REQUESTED;
+ * - the status file (`crewly update-status`) and the pending-upgrade marker.
+ *
+ * @module services/system/auto-update.utils
+ */
+/** What kind of install the running copy is. */
+export type InstallKind = 'npm-global' | 'dev-checkout' | 'unmanaged';
+/** Where and how the running copy is installed. */
+export interface InstallInfo {
+    /** Install kind */
+    kind: InstallKind;
+    /** Real path of the Crewly package root (null when not found) */
+    packageRoot: string | null;
+    /** npm prefix the package lives under (npm-global only) */
+    prefix: string | null;
+    /** Human-readable reason, used in the skip log line */
+    detail: string;
+}
+/** Why auto-update is on or off. */
+export type AutoUpdateSwitch = 'enabled' | 'disabled-setting' | 'disabled-env' | 'enabled-env';
+/** How the last auto-update attempt ended. */
+export type AutoUpdateOutcome = 'up-to-date' | 'deferred-busy' | 'installed-restarting' | 'upgraded' | 'install-failed' | 'verify-failed' | 'restart-unavailable' | 'check-failed' | 'skipped';
+/** Persisted status of the auto-updater (`<crewlyHome>/auto-update-state.json`). */
+export interface AutoUpdateState {
+    /** Version this backend is running */
+    currentVersion: string | null;
+    /** Latest version the registry reported */
+    latestVersion: string | null;
+    /** ISO time of the last registry check */
+    lastCheckAt: string | null;
+    /** Whether the updater would act, and why not when it would not */
+    mode: string;
+    /** How the last attempt ended */
+    lastResult: {
+        outcome: AutoUpdateOutcome;
+        at: string;
+        version?: string;
+        message?: string;
+    } | null;
+    /** Failed attempts in a row (reset on success) */
+    consecutiveFailures: number;
+    /** ISO time before which no new attempt is made */
+    backoffUntil: string | null;
+    /** Target version the owner was already told about (one failure DM per version) */
+    failureNotifiedVersion: string | null;
+}
+/** Marker persisted before an upgrade restart and read on the next boot. */
+export interface PendingUpgradeMarker {
+    /** Version the process was running before the restart */
+    fromVersion: string;
+    /** Version that was installed */
+    toVersion: string;
+    /** ISO time the marker was written */
+    at: string;
+}
+/**
+ * Resolve symlinks when the path exists.
+ *
+ * @param p - Path
+ * @returns Real path, or the resolved path when it does not exist
+ */
+export declare function realOrResolved(p: string): string;
+/**
+ * Walk up from `startDir` to the directory whose package.json is `crewly`.
+ *
+ * @param startDir - Directory to start from
+ * @returns The package root, or null when none is found
+ */
+export declare function findCrewlyPackageRoot(startDir: string): string | null;
+/**
+ * Package root of the running backend, anchored on the entry script
+ * (`process.argv[1]`, e.g. `<root>/dist/backend/backend/src/index.js`) rather
+ * than the cwd — after `npm install -g` replaces the package directory the
+ * old cwd no longer exists.
+ *
+ * @param argv1 - Entry script path (defaults to process.argv[1])
+ * @param cwd - Fallback start directory
+ * @returns Real path of the package root, or null
+ */
+export declare function resolveRunningPackageRoot(argv1?: string | undefined, cwd?: string): string | null;
+/**
+ * The npm prefix a package root was installed under, when it is a global
+ * install: `<prefix>/lib/node_modules/crewly` on POSIX,
+ * `<prefix>\node_modules\crewly` on Windows. Covers the default global prefix
+ * (nvm, Homebrew, /usr/local) and the user prefix (`<crewlyHome>/npm-global`)
+ * alike — installing with `--prefix <that>` replaces exactly the running copy
+ * even when a different `npm` is first on PATH.
+ *
+ * @param packageRoot - Real path of the package root
+ * @param platform - Platform (tests)
+ * @returns The prefix, or null for anything that is not a global install
+ *
+ * @example
+ * ```ts
+ * derivePrefixFromPackageRoot('/usr/local/lib/node_modules/crewly'); // '/usr/local'
+ * derivePrefixFromPackageRoot('/home/me/.crewly/npm-global/lib/node_modules/crewly'); // '/home/me/.crewly/npm-global'
+ * derivePrefixFromPackageRoot('/home/me/proj/node_modules/crewly'); // null (local dependency)
+ * ```
+ */
+export declare function derivePrefixFromPackageRoot(packageRoot: string, platform?: NodeJS.Platform): string | null;
+/**
+ * Whether a directory is a git working tree root (`.git` directory, or the
+ * `.git` file of a worktree).
+ *
+ * @param dir - Directory
+ * @returns True when `.git` exists there
+ */
+export declare function isGitWorkingTree(dir: string): boolean;
+/**
+ * Classify the running install.
+ *
+ * - `dev-checkout`: the package root is a git working tree (e.g. the owner's
+ *   `crewly/` repo running its own build, or an `npm link` that resolves into
+ *   it). It must never npm-install over itself.
+ * - `npm-global`: the root sits in `<prefix>/lib/node_modules/crewly`.
+ * - `unmanaged`: anything else (Docker image at /app, a local dependency, an
+ *   npx cache) — nobody owns an in-place upgrade there.
+ *
+ * @param packageRoot - Real path of the package root (null when unknown)
+ * @param platform - Platform (tests)
+ * @returns Install info
+ */
+export declare function detectInstall(packageRoot: string | null, platform?: NodeJS.Platform): InstallInfo;
+/**
+ * `npm` arguments that install `crewly@<version>` over the running copy.
+ *
+ * @param prefix - Prefix from {@link derivePrefixFromPackageRoot}
+ * @param version - Exact target version
+ * @returns Arguments for npm
+ *
+ * @example
+ * ```ts
+ * npmInstallArgs('/usr/local', '1.20.144');
+ * // ['install', '-g', '--prefix', '/usr/local', 'crewly@1.20.144']
+ * ```
+ */
+export declare function npmInstallArgs(prefix: string, version: string): string[];
+/**
+ * The npm executable that belongs to the running node, when it sits next to
+ * it (nvm, official installers); plain `npm` from PATH otherwise.
+ *
+ * @param execPath - Running node binary (defaults to process.execPath)
+ * @param platform - Platform (tests)
+ * @returns Command to run
+ */
+export declare function resolveNpmCommand(execPath?: string, platform?: NodeJS.Platform): string;
+/**
+ * Version in `<packageRoot>/package.json`, read fresh from disk.
+ *
+ * @param packageRoot - Package root
+ * @returns The version, or null when unreadable
+ */
+export declare function readInstalledVersion(packageRoot: string): string | null;
+/**
+ * Whether `latest` is a strictly newer semver than `current`
+ * (numeric major.minor.patch; pre-release tags are ignored).
+ *
+ * @param latest - Candidate version
+ * @param current - Running version
+ * @returns True when latest > current
+ */
+export declare function isNewerVersion(latest: string, current: string): boolean;
+/**
+ * Resolve the on/off switch: the env override wins over the setting.
+ *
+ * @param settingValue - `settings.general.autoUpdate` (undefined = default on)
+ * @param env - Environment
+ * @returns The switch state
+ *
+ * @example
+ * ```ts
+ * resolveAutoUpdateSwitch(true, { CREWLY_AUTO_UPDATE: '0' }); // 'disabled-env'
+ * resolveAutoUpdateSwitch(false, {}); // 'disabled-setting'
+ * ```
+ */
+export declare function resolveAutoUpdateSwitch(settingValue: boolean | undefined, env?: NodeJS.ProcessEnv): AutoUpdateSwitch;
+/**
+ * Whether a switch state means "on".
+ *
+ * @param state - Switch state
+ * @returns True when enabled
+ */
+export declare function isSwitchOn(state: AutoUpdateSwitch): boolean;
+/**
+ * Read the command line of a process (POSIX only; `/proc` on Linux, `ps`
+ * elsewhere).
+ *
+ * @param pid - Process id
+ * @returns The command line, or null
+ */
+export declare function readProcessCommandLine(pid: number): string | null;
+/**
+ * Whether a supervisor will respawn the backend after it exits with
+ * RESTART_REQUESTED. That supervisor is `crewly start` (foreground, under the
+ * macOS login-item wrapper, under systemd, or under the desktop app). New
+ * CLIs say so in the env; an older CLI parent is recognised by its command line.
+ *
+ * @param env - Environment
+ * @param parentCommandLine - Reader for the parent's command line (tests)
+ * @returns True when a respawning parent is present
+ */
+export declare function hasRestartSupervisor(env?: NodeJS.ProcessEnv, parentCommandLine?: () => string | null): boolean;
+/**
+ * A fresh, empty state.
+ *
+ * @returns Default state
+ */
+export declare function emptyAutoUpdateState(): AutoUpdateState;
+/**
+ * Read the status file; missing or malformed → empty state.
+ *
+ * @param file - Path of the status file
+ * @returns The state
+ */
+export declare function readAutoUpdateState(file: string): AutoUpdateState;
+/**
+ * Write the status file atomically (temp file + rename).
+ *
+ * @param file - Path of the status file
+ * @param state - State to write
+ */
+export declare function writeAutoUpdateState(file: string, state: AutoUpdateState): void;
+/**
+ * Write the pending-upgrade marker.
+ *
+ * @param file - Marker path
+ * @param marker - Contents
+ */
+export declare function writePendingMarker(file: string, marker: PendingUpgradeMarker): void;
+/**
+ * Read and delete the pending-upgrade marker. It is removed even when
+ * malformed, so a crash loop can never repeat the notice.
+ *
+ * @param file - Marker path
+ * @returns The marker, or null when absent or malformed
+ */
+export declare function consumePendingMarker(file: string): PendingUpgradeMarker | null;
+/**
+ * Owner notice after a successful auto-upgrade.
+ *
+ * @param version - New version
+ * @param deviceName - This machine's name
+ * @returns The one-line notice
+ */
+export declare function composeUpgradedNotice(version: string, deviceName: string): string;
+/**
+ * Owner notice after repeated failures.
+ *
+ * @param version - Target version
+ * @param deviceName - This machine's name
+ * @param failures - Failures in a row
+ * @param reason - Last failure reason
+ * @returns The notice text
+ */
+export declare function composeFailureNotice(version: string, deviceName: string, failures: number, reason: string): string;
+//# sourceMappingURL=auto-update.utils.d.ts.map

package/dist/cli/backend/src/services/system/auto-update.utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auto-update.utils.d.ts","sourceRoot":"","sources":["../../../../../../backend/src/services/system/auto-update.utils.ts"],"names":[],"mappings":"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"}