@parall/agent-core 1.36.1 → 1.38.0

package/dist/lane-ledger.js

@@ -0,0 +1,333 @@
+import * as fs from 'node:fs';
+import { ApiError } from '@parall/sdk';
+import { laneContextFilePath, laneKeyForTarget } from './lane-key.js';
+/**
+ * Thrown when the server predates the dispatch ledger (claim endpoint 404s
+ * during a rolling deploy). The gateway falls back to the legacy
+ * received/ack flow for the rest of its lifetime.
+ */
+export class LedgerUnsupportedError extends Error {
+}
+function isStaleLane(err) {
+    return err instanceof ApiError && err.status === 409 && err.code === 'STALE_LANE';
+}
+function isNotFound(err) {
+    return err instanceof ApiError && err.status === 404;
+}
+/**
+ * A pre-ledger server (or an edge that doesn't know the route) answers the
+ * claim endpoint with an UNSTRUCTURED 404 — no app error code. Our own
+ * handlers always attach a code, so a coded 404 is a semantic answer, not a
+ * missing endpoint. Transient edge 404s during rolling deploys are further
+ * contained by the reconnect re-probe (ledgerDisabled resets on hello).
+ */
+function isEndpointMissing(err) {
+    return err instanceof ApiError && err.status === 404 && !err.code;
+}
+/**
+ * LaneLedger is the bridge-side client of the server dispatch ledger
+ * (docs/engineering-design/agent-dispatch-idempotency-design.md): it claims
+ * lane occupancy just-in-time before a message dispatch, folds mid-turn
+ * same-target messages via steer, completes (no_action sweep + release) when
+ * the local queue for a lane runs dry, and releases leftovers on shutdown.
+ *
+ * It is also the single writer of the per-lane dispatch context files under
+ * PRLL_CONTEXT_DIR (`<lane-key>.json`) that the CLI reads to derive dispatch
+ * effect keys. The CLI's reply-state sidecar lives next to it and is never
+ * touched here (two writers, two files).
+ */
+export class LaneLedger {
+    opts;
+    lanes = new Map();
+    constructor(opts) {
+        this.opts = opts;
+    }
+    get contextDir() {
+        return this.opts.contextDir;
+    }
+    /** Only chat message events ride the lane ledger; typed events stay on the legacy ack path. */
+    handles(event) {
+        return event.type === 'message' && event.targetId.startsWith('cht_');
+    }
+    laneKeyFor(event) {
+        if (event.type !== 'message' && event.dispatchEventId) {
+            return laneKeyForTarget(`dsp:${event.dispatchEventId}`);
+        }
+        return laneKeyForTarget(`prll://${event.targetId}`, event.threadRootId);
+    }
+    getForEvent(event) {
+        return this.lanes.get(this.laneKeyFor(event));
+    }
+    laneContextPath(lane) {
+        return laneContextFilePath(this.opts.contextDir, lane.targetUri, lane.threadRootId);
+    }
+    /**
+     * Claim (or reuse) the lane for a group of same-lane message events and
+     * fold every group member into it. Returns 'foreign' when a healthy
+     * incumbent (another pod) holds the resource — the caller must not
+     * dispatch; the events stay pending server-side and re-drive after the
+     * incumbent completes.
+     */
+    async ensureLane(events) {
+        const trigger = events[events.length - 1];
+        const laneKey = this.laneKeyFor(trigger);
+        let lane = this.lanes.get(laneKey);
+        if (!lane) {
+            const targetUri = `prll://${trigger.targetId}`;
+            let res;
+            try {
+                res = await this.opts.client.claimDispatch(this.opts.orgId, {
+                    target_uri: targetUri,
+                    thread_root_id: trigger.threadRootId,
+                    limit: 100,
+                });
+            }
+            catch (err) {
+                if (isEndpointMissing(err))
+                    throw new LedgerUnsupportedError('claim endpoint unavailable');
+                throw err;
+            }
+            if (!res.claimed || !res.lane) {
+                this.opts.log?.info(`lane for ${targetUri} held by a healthy incumbent — leaving events pending for re-drive`);
+                return null;
+            }
+            const leaseUntilMs = Date.parse(res.lease_until ?? '');
+            lane = {
+                laneKey,
+                lane: res.lane,
+                targetUri,
+                threadRootId: trigger.threadRootId,
+                folded: new Map(),
+                ...(Number.isNaN(leaseUntilMs)
+                    ? {}
+                    : { leaseUntilMs, leaseTtlMs: Math.max(leaseUntilMs - Date.now(), 60_000) }),
+            };
+            for (const ev of res.events ?? []) {
+                lane.folded.set(ev.source_id, ev.id);
+            }
+            this.lanes.set(laneKey, lane);
+        }
+        // Fold group members the claim didn't cover (they arrived after the
+        // claim, or this group reuses an already-active lane). Fail closed on ANY
+        // fold failure: an un-folded message dispatched now would not be covered
+        // by this lane's reply/complete, so its still-live WorkItem would re-drive
+        // later and the model would handle it twice. Releasing hands the folded
+        // members back to pending immediately; the re-drive / live hint path
+        // re-delivers the whole group under a fresh claim.
+        for (const ev of events) {
+            if (lane.folded.has(ev.messageId))
+                continue;
+            try {
+                const res = await this.opts.client.steerDispatch(this.opts.orgId, {
+                    lane: lane.lane,
+                    target_uri: lane.targetUri,
+                    thread_root_id: lane.threadRootId,
+                    ...(ev.dispatchEventId
+                        ? { dispatch_event_id: ev.dispatchEventId }
+                        : { source_type: 'message', source_id: ev.messageId }),
+                });
+                lane.folded.set(ev.messageId, res.dispatch_event_id);
+            }
+            catch (err) {
+                if (isStaleLane(err)) {
+                    // We lost the lane mid-group — drop local state; the takeover
+                    // owner (or the next claim) picks the members up.
+                    this.lanes.delete(laneKey);
+                    return null;
+                }
+                this.opts.log?.warn(`steer fold failed for ${ev.messageId} — failing closed, releasing lane: ${String(err)}`);
+                await this.release(laneKey);
+                return null;
+            }
+        }
+        return lane;
+    }
+    /**
+     * Fold a live mid-turn message into its active lane BEFORE injecting it
+     * into the running turn. Injection without a successful fold is forbidden —
+     * an un-folded injected message would be re-driven after complete and the
+     * model would handle it twice.
+     */
+    async steerLive(event) {
+        const laneKey = this.laneKeyFor(event);
+        const lane = this.lanes.get(laneKey);
+        if (!lane)
+            return false;
+        if (lane.folded.has(event.messageId))
+            return true;
+        try {
+            const res = await this.opts.client.steerDispatch(this.opts.orgId, {
+                lane: lane.lane,
+                target_uri: lane.targetUri,
+                thread_root_id: lane.threadRootId,
+                ...(event.dispatchEventId
+                    ? { dispatch_event_id: event.dispatchEventId }
+                    : { source_type: 'message', source_id: event.messageId }),
+            });
+            lane.folded.set(event.messageId, res.dispatch_event_id);
+            return true;
+        }
+        catch (err) {
+            if (isStaleLane(err)) {
+                this.lanes.delete(laneKey);
+            }
+            else {
+                this.opts.log?.warn(`live steer failed for ${event.messageId}: ${String(err)}`);
+            }
+            return false;
+        }
+    }
+    /**
+     * Complete the lane when no local work remains for it: the server sweeps
+     * still-leased members as no_action, releases the occupancy row, and
+     * re-drives any same-target pending work. A STALE_LANE answer means a
+     * takeover already owns the resource — local state is dropped either way.
+     */
+    async completeIfIdle(laneKey, hasMoreLocal) {
+        const lane = this.lanes.get(laneKey);
+        if (!lane || hasMoreLocal)
+            return;
+        this.lanes.delete(laneKey);
+        this.removeLaneContext(lane);
+        try {
+            const res = await this.opts.client.completeDispatch(this.opts.orgId, {
+                lane: lane.lane,
+                target_uri: lane.targetUri,
+                thread_root_id: lane.threadRootId,
+            });
+            if (res.swept_no_action > 0 || res.redriven) {
+                this.opts.log?.info(`lane complete for ${lane.targetUri}: swept ${res.swept_no_action} no_action, redriven=${res.redriven}`);
+            }
+        }
+        catch (err) {
+            if (isStaleLane(err)) {
+                this.opts.log?.info(`lane complete skipped for ${lane.targetUri} — taken over`);
+                return;
+            }
+            // Lease expiry recovers the members; complete is not retried here.
+            this.opts.log?.warn(`lane complete failed for ${lane.targetUri}: ${String(err)}`);
+        }
+    }
+    /**
+     * Long-turn keepalive: renew the lane's lease on runtime activity, throttled
+     * so a chatty turn doesn't spam the server. Without this, a legitimately
+     * long turn (> lane TTL) would be dethroned mid-flight and every subsequent
+     * write misfired with STALE_LANE — the design doc's "long turns renew via
+     * step writes". Fire-and-forget: a failed renewal is surfaced by the next
+     * write's incumbency check anyway.
+     */
+    maybeRenew(lane) {
+        const now = Date.now();
+        // Server-driven pacing: renew once less than half the lease TTL remains.
+        // Hardcoding a client-side rhythm would silently break every published
+        // runtime image the day the server shortens its lane TTL.
+        const ttl = lane.leaseTtlMs ?? 10 * 60_000;
+        const until = lane.leaseUntilMs ?? now; // unknown lease → renew now
+        if (until - now > ttl / 2)
+            return;
+        lane.leaseUntilMs = now + ttl; // optimistic; corrected by the response
+        void this.opts.client
+            .heartbeatDispatchLane(this.opts.orgId, {
+            lane: lane.lane,
+            target_uri: lane.targetUri,
+            thread_root_id: lane.threadRootId,
+        })
+            .then((res) => {
+            const until = Date.parse(res?.lease_until ?? '');
+            if (!Number.isNaN(until))
+                lane.leaseUntilMs = until;
+        })
+            .catch((err) => {
+            if (isStaleLane(err)) {
+                this.lanes.delete(lane.laneKey);
+                this.opts.log?.warn(`lane ${lane.targetUri} was taken over during the turn`);
+                return;
+            }
+            this.opts.log?.warn(`lane heartbeat failed for ${lane.targetUri}: ${String(err)}`);
+        });
+    }
+    /**
+     * Release a lane's unresolved members back to pending (dispatch error /
+     * shutdown) so the next pod re-claims immediately instead of waiting out
+     * the lease.
+     */
+    async release(laneKey) {
+        const lane = this.lanes.get(laneKey);
+        if (!lane)
+            return;
+        this.lanes.delete(laneKey);
+        this.removeLaneContext(lane);
+        try {
+            await this.opts.client.releaseDispatchLane(this.opts.orgId, lane.lane);
+        }
+        catch (err) {
+            this.opts.log?.warn(`lane release failed for ${lane.targetUri}: ${String(err)}`);
+        }
+    }
+    async releaseAll() {
+        const keys = [...this.lanes.keys()];
+        for (const key of keys) {
+            await this.release(key);
+        }
+    }
+    /** True when any lane is currently active (used by shutdown logging). */
+    get activeCount() {
+        return this.lanes.size;
+    }
+    /**
+     * Claim the single-member lane of one typed WorkItem (resource = dsp:<id>),
+     * by WorkItem id or by source identity (the live task.assigned event has no
+     * WorkItem id). Returns null when a healthy incumbent (another pod) holds
+     * it or the WorkItem is already resolved — the caller must skip processing.
+     */
+    async claimTyped(ref) {
+        let res;
+        try {
+            res = await this.opts.client.claimDispatch(this.opts.orgId, {
+                dispatch_event_id: ref.dispatchEventId,
+                source_type: ref.dispatchEventId ? undefined : ref.sourceType,
+                source_id: ref.dispatchEventId ? undefined : ref.sourceId,
+            });
+        }
+        catch (err) {
+            if (isEndpointMissing(err))
+                throw new LedgerUnsupportedError('claim endpoint unavailable');
+            throw err;
+        }
+        if (!res.claimed || !res.lane || !res.events?.length)
+            return null;
+        const workItem = res.events[0];
+        const targetUri = `dsp:${workItem.id}`;
+        const leaseUntilMs = Date.parse(res.lease_until ?? '');
+        const lane = {
+            laneKey: laneKeyForTarget(targetUri),
+            lane: res.lane,
+            targetUri,
+            folded: new Map([[workItem.source_id, workItem.id]]),
+            typedDispatchEventId: workItem.id,
+            ...(Number.isNaN(leaseUntilMs)
+                ? {}
+                : { leaseUntilMs, leaseTtlMs: Math.max(leaseUntilMs - Date.now(), 60_000) }),
+        };
+        this.lanes.set(lane.laneKey, lane);
+        return lane;
+    }
+    /**
+     * Remove the per-lane context file (and its CLI sidecar) when the lane
+     * ends. A leftover file would make a later cross-context send to the same
+     * target bind a dead lane token and misfire with STALE_LANE instead of
+     * taking the plain non-ledger path.
+     */
+    removeLaneContext(lane) {
+        const contextPath = this.laneContextPath(lane);
+        for (const p of [contextPath, contextPath.replace(/\.json$/, '.reply-state.json')]) {
+            try {
+                fs.rmSync(p, { force: true });
+            }
+            catch {
+                // Best-effort: a stale file only re-surfaces as a server-side
+                // STALE_LANE, never as a wrong write.
+            }
+        }
+    }
+}

package/dist/platform-config.d.ts

@@ -3,6 +3,7 @@ import type { GatewayLogger } from './dispatch-adapter.js';
 export interface PlatformDefaults {
     model: string | null;
     thinkingEffort: string | null;
+    modelIsPin?: boolean;
 }
 export interface PlatformConfigManager {
     fetch(): Promise<PlatformDefaults>;
@@ -13,6 +14,12 @@ export interface PlatformManagementProfile {
     machine_id?: string | null;
     model_management?: string | null;
 }
+/**
+ * @deprecated Bridges now derive pin-vs-floor via {@link deriveModelIsPin}
+ * (presence-gated dual-read of the server's `model_is_pin`). This is retained
+ * only as the legacy fallback inside `deriveModelIsPin` (for old servers that
+ * omit the field) and for any third-party consumers. Prefer `deriveModelIsPin`.
+ */
 export declare function isPlatformManagedProfile(profile: PlatformManagementProfile | null | undefined): boolean;
 /**
  * Whether the platform-delivered model should be treated as an operator
@@ -23,6 +30,10 @@ export declare function isPlatformManagedProfile(profile: PlatformManagementProf
  * are not. Pass the result as `resolveRuntimeModel`'s first argument. Keeping
  * this derivation in one place avoids drift across the bridges' (re)config
  * sites where the subtle null-hosted-vs-explicit-self distinction matters.
+ *
+ * @deprecated Used only as the legacy fallback inside {@link deriveModelIsPin}
+ * (old servers that omit `model_is_pin`). New code should read `model_is_pin`
+ * via `deriveModelIsPin` rather than calling this directly.
  */
 export declare function isPlatformModelOverride(profile: PlatformManagementProfile | null | undefined): boolean;
 /**
@@ -40,6 +51,14 @@ export declare function isPlatformModelOverride(profile: PlatformManagementProfi
  * the server delivers no floor.
  */
 export declare function resolveRuntimeModel(isOperatorOverride: boolean, platformModel: string | null, configModel: string | null | undefined): string | undefined;
+/**
+ * Whether the platform-delivered model is an operator PIN (override) vs a catalog
+ * FLOOR. Presence-gated dual-read: a new server sends `model_is_pin` (use it); an
+ * old server omits it (`undefined`) so we fall back to the legacy
+ * `model_management`-derived signal. Pass the result to `resolveRuntimeModel`.
+ */
+export declare function deriveModelIsPin(defaults: PlatformDefaults, profile: PlatformManagementProfile | null | undefined): boolean;
+export declare function extractDefaults(config: Record<string, unknown>, runtimeType: string | undefined): Omit<PlatformDefaults, 'modelIsPin'>;
 export declare function createPlatformConfigManager(opts: {
     client: ParallClient;
     stateDir: string;

package/dist/platform-config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"platform-config.d.ts","sourceRoot":"","sources":["../src/platform-config.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAA0B,MAAM,aAAa,CAAC;AACxE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAE3D,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/B;AAED,MAAM,WAAW,qBAAqB;IACpC,KAAK,IAAI,OAAO,CAAC,gBAAgB,CAAC,CAAC;IACnC,OAAO,IAAI,gBAAgB,CAAC;IAC5B,SAAS,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;CAC7C;AAED,MAAM,WAAW,yBAAyB;IACxC,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,gBAAgB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAClC;AAED,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,yBAAyB,GAAG,IAAI,GAAG,SAAS,GACpD,OAAO,CAET;AAED;;;;;;;;;GASG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,yBAAyB,GAAG,IAAI,GAAG,SAAS,GACpD,OAAO,CAET;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,mBAAmB,CACjC,kBAAkB,EAAE,OAAO,EAC3B,aAAa,EAAE,MAAM,GAAG,IAAI,EAC5B,WAAW,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GACrC,MAAM,GAAG,SAAS,CAGpB;AA8ED,wBAAgB,2BAA2B,CAAC,IAAI,EAAE;IAChD,MAAM,EAAE,YAAY,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,GAAG,CAAC,EAAE,aAAa,CAAC;CACrB,GAAG,qBAAqB,CAwDxB"}
+{"version":3,"file":"platform-config.d.ts","sourceRoot":"","sources":["../src/platform-config.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAA0B,MAAM,aAAa,CAAC;AACxE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAE3D,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAK9B,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED,MAAM,WAAW,qBAAqB;IACpC,KAAK,IAAI,OAAO,CAAC,gBAAgB,CAAC,CAAC;IACnC,OAAO,IAAI,gBAAgB,CAAC;IAC5B,SAAS,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;CAC7C;AAED,MAAM,WAAW,yBAAyB;IACxC,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,gBAAgB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAClC;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,yBAAyB,GAAG,IAAI,GAAG,SAAS,GACpD,OAAO,CAET;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,yBAAyB,GAAG,IAAI,GAAG,SAAS,GACpD,OAAO,CAET;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,mBAAmB,CACjC,kBAAkB,EAAE,OAAO,EAC3B,aAAa,EAAE,MAAM,GAAG,IAAI,EAC5B,WAAW,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GACrC,MAAM,GAAG,SAAS,CAGpB;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,gBAAgB,EAC1B,OAAO,EAAE,yBAAyB,GAAG,IAAI,GAAG,SAAS,GACpD,OAAO,CAET;AA6ED,wBAAgB,eAAe,CAC7B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,WAAW,EAAE,MAAM,GAAG,SAAS,GAC9B,IAAI,CAAC,gBAAgB,EAAE,YAAY,CAAC,CAwBtC;AAED,wBAAgB,2BAA2B,CAAC,IAAI,EAAE;IAChD,MAAM,EAAE,YAAY,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,GAAG,CAAC,EAAE,aAAa,CAAC;CACrB,GAAG,qBAAqB,CA4ExB"}

package/dist/platform-config.js

@@ -1,5 +1,11 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
+/**
+ * @deprecated Bridges now derive pin-vs-floor via {@link deriveModelIsPin}
+ * (presence-gated dual-read of the server's `model_is_pin`). This is retained
+ * only as the legacy fallback inside `deriveModelIsPin` (for old servers that
+ * omit the field) and for any third-party consumers. Prefer `deriveModelIsPin`.
+ */
 export function isPlatformManagedProfile(profile) {
     return profile?.machine_id != null || profile?.model_management === 'platform';
 }
@@ -12,6 +18,10 @@ export function isPlatformManagedProfile(profile) {
  * are not. Pass the result as `resolveRuntimeModel`'s first argument. Keeping
  * this derivation in one place avoids drift across the bridges' (re)config
  * sites where the subtle null-hosted-vs-explicit-self distinction matters.
+ *
+ * @deprecated Used only as the legacy fallback inside {@link deriveModelIsPin}
+ * (old servers that omit `model_is_pin`). New code should read `model_is_pin`
+ * via `deriveModelIsPin` rather than calling this directly.
  */
 export function isPlatformModelOverride(profile) {
     return isPlatformManagedProfile(profile) && profile?.model_management !== 'self';
@@ -34,6 +44,15 @@ export function resolveRuntimeModel(isOperatorOverride, platformModel, configMod
     const operatorOverride = isOperatorOverride ? platformModel : null;
     return operatorOverride ?? configModel ?? platformModel ?? undefined;
 }
+/**
+ * Whether the platform-delivered model is an operator PIN (override) vs a catalog
+ * FLOOR. Presence-gated dual-read: a new server sends `model_is_pin` (use it); an
+ * old server omits it (`undefined`) so we fall back to the legacy
+ * `model_management`-derived signal. Pass the result to `resolveRuntimeModel`.
+ */
+export function deriveModelIsPin(defaults, profile) {
+    return defaults.modelIsPin !== undefined ? defaults.modelIsPin : isPlatformModelOverride(profile);
+}
 const CACHE_FILENAME = 'parall-platform-config.json';
 const SUPPORTED_SCHEMA_VERSION = 1;
 function cachePath(stateDir) {
@@ -52,6 +71,7 @@ function saveCache(stateDir, response) {
     const cached = {
         version: response.version,
         config: response.config,
+        modelIsPin: response.model_is_pin,
         fetchedAt: new Date().toISOString(),
     };
     const filePath = cachePath(stateDir);
@@ -62,23 +82,46 @@ function saveCache(stateDir, response) {
 }
 function runtimeModelName(canonicalModel, runtimeType, config) {
     const runtime = runtimeType?.trim();
-    if (!runtime || runtime === 'openclaw')
+    if (!runtime || runtime === 'openclaw' || runtime === 'hermes')
         return canonicalModel;
     const models = (config.models ?? {});
     const providers = (models.providers ?? {});
     const parall = (providers.parall ?? {});
     const catalog = Array.isArray(parall.models) ? parall.models : [];
     const match = catalog.find((model) => model.id === canonicalModel);
-    const runtimeNames = (match?.runtime_names ?? {});
+    // Unknown to the catalog: let the bridge fall back to env/default.
+    if (!match)
+        return null;
+    const runtimeNames = (match.runtime_names ?? {});
     const runtimeName = runtimeNames[runtime];
-    return typeof runtimeName === 'string' && runtimeName ? runtimeName : null;
+    if (typeof runtimeName === 'string' && runtimeName)
+        return runtimeName;
+    // Cross-family on the Parall proxy route: this catalog model carries no
+    // native name for this runtime's CLI. Fall back to the canonical
+    // provider/model id — the Parall proxy accepts it and routes via OpenRouter's
+    // universal skin, so the CLI's native wire format still reaches the upstream.
+    // Mirrors the server's RuntimeModelName; only reachable on the Parall route
+    // (own routes are family-locked at write time to same-family models).
+    return canonicalModel;
 }
-function extractDefaults(config, runtimeType) {
+// Exported for unit testing of the proxy-prefix normalization (see
+// test/platform-config.test.mjs). Not part of the bridge-facing API surface.
+// modelIsPin is NOT extracted here — it lives on the response/cache envelope
+// (a sibling of `config`), so callers compose it in themselves.
+export function extractDefaults(config, runtimeType) {
     const agents = (config.agents ?? {});
     const defaults = (agents.defaults ?? {});
     let model = null;
     if (typeof defaults.model === 'string' && defaults.model) {
-        const canonicalModel = defaults.model.replace(/^parall\//, '');
+        // Strip the proxy prefix before catalog translation. OpenClaw writers may
+        // rewrite parall/anthropic/... → parall-anthropic/anthropic/... (prompt-cache
+        // transport); both are proxy forms and a shared LKG cache can hold either.
+        // Strip parall-anthropic/ first, then any remaining parall/ — sequential
+        // (not either/or) and both via the same anchored regex, so a doubly-prefixed
+        // value normalizes fully and the two branches can't diverge on edge cases.
+        const canonicalModel = defaults.model
+            .replace(/^parall-anthropic\//, '')
+            .replace(/^parall\//, '');
         model = runtimeModelName(canonicalModel, runtimeType, config);
     }
     let thinkingEffort = null;
@@ -90,13 +133,30 @@ function extractDefaults(config, runtimeType) {
 export function createPlatformConfigManager(opts) {
     const { client, stateDir, runtimeType, log } = opts;
     let cachedVersion;
-    let currentDefaults = { model: null, thinkingEffort: null };
+    let currentDefaults = {
+        model: null,
+        thinkingEffort: null,
+        modelIsPin: undefined,
+    };
     let currentRawConfig = null;
     const cached = loadCache(stateDir);
     if (cached) {
-        cachedVersion = cached.version;
+        // Pre-model_is_pin cache schema (no modelIsPin field): keep the LKG
+        // defaults, but DROP the ETag so the next fetch returns a full 200 and
+        // rewrites the cache in the new schema. With the ETag, a server whose
+        // config hasn't changed would 304 forever and strand
+        // modelIsPin=undefined (permanent legacy model_management fallback) on a
+        // fully-upgraded stack — the rollout order "server first, bridge later"
+        // makes an old-schema cache holding a CURRENT ETag the normal case.
+        // Against an old server (which never sends model_is_pin) this costs one
+        // full fetch per process start; acceptable, and disappears once the
+        // server is upgraded.
+        cachedVersion = cached.modelIsPin === undefined ? undefined : cached.version;
         currentRawConfig = cached.config;
-        currentDefaults = extractDefaults(cached.config, runtimeType);
+        currentDefaults = {
+            ...extractDefaults(cached.config, runtimeType),
+            modelIsPin: cached.modelIsPin,
+        };
     }
     return {
         async fetch() {
@@ -123,7 +183,10 @@ export function createPlatformConfigManager(opts) {
             saveCache(stateDir, fresh);
             cachedVersion = fresh.version;
             currentRawConfig = fresh.config;
-            currentDefaults = extractDefaults(fresh.config, runtimeType);
+            currentDefaults = {
+                ...extractDefaults(fresh.config, runtimeType),
+                modelIsPin: fresh.model_is_pin,
+            };
             return currentDefaults;
         },
         current() {

package/dist/prompt-fragments.d.ts

@@ -18,7 +18,7 @@ export declare function buildIdentity(agent?: AgentIdentity): string;
 /** @deprecated Use buildIdentity() instead. Kept for backward compat during migration. */
 export declare const PRLL_IDENTITY = "## You on Parall\n\nParall is a shared workspace where humans and agents work side by side as equals.\nYou are a participant here, not a service. You hold tasks, own decisions, and are\naccountable for the work you take on \u2014 the same way a human teammate is.\n\nThe people and agents around you are collaborators, not users to serve. Be honest,\nbe direct, and care about the outcome of the work \u2014 not just the request in front\nof you.";
 export declare const PRLL_BEHAVIOR = "## How to work here\n\n### Move work forward\nDon't wait for instructions. If you see the next step, take it. If something is\nambiguous, clarify once and proceed. If you're blocked, say what's blocking you\n\u2014 don't go silent. Initiative is expected.\n\n### Work in the open\nNothing you do exists until the system can see it. Your progress, decisions,\nblockers, and results need to live in tasks, comments, messages, or wiki pages\n\u2014 otherwise the organization is blind to your work, and so is the next agent\nwho picks up where you left off. Leave traces as you go, not at the end.\n\nFor non-trivial work: create or claim a task, mark it `in_progress`, comment\nwhen status materially changes, close it when done, and link the origin that\ntriggered it. Details: load the `parall-tasks` skill.\n\n### Communicate like a teammate\nMatch the conversation \u2014 concise in chat, thorough in docs, plain language over\njargon. Say what matters; stop when you're done. Don't narrate every tool call\nor pad replies to seem thorough.\n\n### Respect what's shared\nYou have broad latitude inside your own work. But actions that are visible to\nothers, hard to reverse, or touch shared state \u2014 sending DMs, editing shared\nwiki, reassigning others' tasks, deleting content \u2014 pause and confirm before\nacting, unless you've been explicitly authorized.\n\n### Shared workspace\nOther agents share this workspace. Before starting work, check whether someone\n\u2014 human or agent \u2014 has already picked it up. Coordination beats racing.\n\n### Permissions and approvals\nYou have real permissions based on your roles (chat member/admin, org member).\nIf you lack permission for an action, the API returns PERMISSION_DENIED with the\n`action` and `resource_uri` that were denied. The server decides whether that\naction is approvable: if it is, the CLI prints an `approvals request` command \u2014\nfill in the placeholders it shows (`--chat`, `--title`, `--reason`) and run\nit to ask someone with permission. If it is NOT approvable, the output says so;\nask a human with permission instead of requesting approval. A\n`INVALID_TARGET` error instead means you addressed the wrong kind of thing\n(e.g. a `usr_` id where a chat is expected) \u2014 follow the message (e.g. use\n`dm` for a user). Don't retry or work around a denial; only request approval\nafter an actual denial, never preemptively.\n\n### When in doubt\nPrefer asking over guessing. Prefer \"I don't know\" over fabricating. Your\ncredibility is what you bring to the workspace \u2014 protect it.";
-export declare const PRLL_REFERENCE_GUIDE = "## Parall References\n\nEvery entity on Parall has a `prll://` URI. Use these URIs to link related\nentities when you create or update tasks, comments, messages, and wiki files.\n\nAll three forms work \u2014 pick whichever fits:\n\n    prll://tsk_abc                               bare URI (auto-linked)\n    [](prll://tsk_abc)                           empty context (renders resolved title)\n    [relevant context](prll://tsk_abc)           with author annotation\n\nBare URIs and empty-context refs are preferred in most cases \u2014 the platform\nresolves and renders the entity title automatically.\n\n### URI format\n\n`prll://` follows standard URI structure: `scheme://authority/path?query#fragment`.\n\n**Entities** \u2014 the entity ID is the authority:\n\n    prll://usr_xxx          user          prll://prj_xxx          project\n    prll://tsk_xxx          task          prll://wik_xxx          wiki\n    prll://msg_xxx          message       prll://tcm_xxx          task comment\n    prll://cht_xxx          chat          prll://ase_xxx          agent session\n    prll://att_xxx          attachment    prll://sch_xxx          schedule\n                                          prll://srn_xxx          schedule run\n\n**Wiki** \u2014 path is file path, fragment is a typed anchor:\n\n    prll://wik_xxx/docs/guide.md                  file\n    prll://wik_xxx/docs/guide.md#h=Auth::OAuth    heading (:: = hierarchy)\n    prll://wik_xxx/src/auth.go?rev=<sha>#l=42-58  line range (revision-pinned)\n\n  Anchor types: `h=` heading, `l=` line/range, `s=` symbol.\n  Line anchors in persistent content require `?rev=<full-40-char-sha>`.\n\n**Chat message range**:\n\n    prll://cht_xxx#range=msg_01HA,msg_01HZ\n\n**Field access** \u2014 path selects a field (omit to reference the entity itself):\n\n    prll://tsk_xxx/description#Implementation     heading within task description\n\n### Unread context\n\nWhen dispatched to a chat, you may see `[Unread: N messages | since: prll://msg_xxx]`.\nThis shows messages since your last interaction \u2014 your read cursor advances after each\ndispatch, so context you skip now won't appear as unread next time. Use\n`parall messages list <chat> --limit 20` to fetch recent context. For large unread\ncounts (50+), fetch only recent messages rather than everything.\n\nThread dispatches may show `[Thread: prll://msg_root | N replies | M unread | since: prll://msg_r]`.\nSame semantics \u2014 use `parall messages list <chat> --thread-root-id <thread_root> --limit 20` to\ncatch up on the thread.\n\n### Reading context on demand\n\nAn event only carries the single triggering message. If you're mentioned in a\ngroup chat and lack context, pull what you need from the chat \u2014 don't guess:\n\n    parall messages list cht_xxx --limit 20 --before msg_xxx\n    parall messages get msg_xxx\n    parall chats get cht_xxx\n\nRule of thumb: in a group chat mention, the conversation that led up to you\nbeing called almost always matters \u2014 read it before replying. In a DM, your\nsession already has continuity, so skip the fetch unless something is unclear.\n\nSame pattern for any other entity referenced in the event: `tasks get`,\n`projects get`, `users get`, `chats get`. Follow the reflink, don't ask.\n\n### File attachments\n\nMessages may include attachments. They appear in events as:\n\n    [Attachment: prll://att_xxx | image/png | 1.2MB | screenshot.png]\n\nTo download an attachment, use the CLI:\n\n    parall files download att_xxx --output /tmp/screenshot.png\n\nTo send a file:\n\n    parall messages send prll://cht_xxx --file /tmp/output.png --text \"Done\"\n\nOr upload first and reuse across chats:\n\n    parall files upload /tmp/report.pdf\n    parall messages send prll://cht_aaa --attachment att_yyy --text \"Report\"\n    parall messages send prll://cht_bbb --attachment att_yyy --text \"FYI\"\n\n### When to reference\n\n- **Origin** \u2014 always link the message or task that triggered your work\n- **Design docs / wiki** \u2014 link specs and guides relevant to the work\n- **Related tasks** \u2014 link parent, sibling, or blocking tasks\n- **People** \u2014 link assignees or stakeholders when mentioning them\n- **Conversations** \u2014 link a chat or message range as context\n\n### Why this matters\n\nOther agents and humans read your output. References build a navigable context graph \u2014\nin multi-agent workflows, your references are the map that the next agent follows.";
+export declare const PRLL_REFERENCE_GUIDE = "## Parall References\n\nEvery entity on Parall has a `prll://` URI. Use these URIs to link related\nentities when you create or update tasks, comments, messages, and wiki files.\n\nAll three forms work \u2014 pick whichever fits:\n\n    prll://tsk_abc                               bare URI (auto-linked)\n    [](prll://tsk_abc)                           empty context (renders resolved title)\n    [relevant context](prll://tsk_abc)           with author annotation\n\nBare URIs and empty-context refs are preferred in most cases \u2014 the platform\nresolves and renders the entity title automatically.\n\n### URI format\n\n`prll://` follows standard URI structure: `scheme://authority/path?query#fragment`.\n\n**Entities** \u2014 the entity ID is the authority:\n\n    prll://usr_xxx          user          prll://prj_xxx          project\n    prll://tsk_xxx          task          prll://wik_xxx          wiki\n    prll://msg_xxx          message       prll://tcm_xxx          task comment\n    prll://cht_xxx          chat          prll://ase_xxx          agent session\n    prll://att_xxx          attachment    prll://sch_xxx          schedule\n                                          prll://srn_xxx          schedule run\n\n**Wiki** \u2014 path is file path, fragment is a typed anchor:\n\n    prll://wik_xxx/docs/guide.md                  file\n    prll://wik_xxx/docs/guide.md#h=Auth::OAuth    heading (:: = hierarchy)\n    prll://wik_xxx/src/auth.go?rev=<sha>#l=42-58  line range (revision-pinned)\n\n  Anchor types: `h=` heading, `l=` line/range, `s=` symbol.\n  Line anchors in persistent content require `?rev=<full-40-char-sha>`.\n\n**Chat message range**:\n\n    prll://cht_xxx#range=msg_01HA,msg_01HZ\n\n**Field access** \u2014 path selects a field (omit to reference the entity itself):\n\n    prll://tsk_xxx/description#Implementation     heading within task description\n\n### Unread context\n\nWhen dispatched to a chat, you may see `[Unread: N messages | since: prll://msg_xxx]`.\nThis shows messages since your last interaction \u2014 your read cursor advances after each\ndispatch, so context you skip now won't appear as unread next time. Use\n`parall messages list <chat> --limit 20` to fetch recent context. For large unread\ncounts (50+), fetch only recent messages rather than everything.\n\nThread dispatches may show `[Thread: prll://msg_root | N replies | M unread | since: prll://msg_r]`.\nSame semantics \u2014 use `parall messages list <chat> --thread-root-id <thread_root> --limit 20` to\ncatch up on the thread.\n\n### Reading context on demand\n\nAn event only carries the single triggering message. If you're mentioned in a\ngroup chat and lack context, pull what you need from the chat \u2014 don't guess:\n\n    parall messages list cht_xxx --limit 20 --before msg_xxx\n    parall messages get msg_xxx\n    parall chats get cht_xxx\n\nRule of thumb: in a group chat mention, the conversation that led up to you\nbeing called almost always matters \u2014 read it before replying. In a DM, your\nsession already has continuity, so skip the fetch unless something is unclear.\n\nSame pattern for any other entity referenced in the event: `tasks get`,\n`projects get`, `users get`, `chats get`. Follow the reflink, don't ask.\n\n### File attachments\n\nMessages may include attachments. They appear in events as:\n\n    [Attachment: prll://att_xxx | image/png | 1.2MB | screenshot.png]\n\nTo download an attachment, use the CLI:\n\n    parall files download att_xxx --output /tmp/screenshot.png\n\nTo send a file:\n\n    parall messages send prll://cht_xxx --file /tmp/output.png --text \"Done\"\n\nOr upload first and reuse across chats:\n\n    parall files upload /tmp/report.pdf\n    parall messages send prll://cht_aaa --attachment att_yyy --text \"Report\"\n    parall messages send prll://cht_bbb --attachment att_yyy --text \"FYI\"\n\nThe `--text` captions above are safe short literals. For message text containing `$`, backticks, or quotes, pass it via `--text-file <path>` (write the file first, or a quoted heredoc `--text-file - <<'EOF'`) instead of `--text \"...\"` \u2014 inside double quotes the shell turns `$1,000` into `,000` and executes `$(...)`.\n\n### When to reference\n\n- **Origin** \u2014 always link the message or task that triggered your work\n- **Design docs / wiki** \u2014 link specs and guides relevant to the work\n- **Related tasks** \u2014 link parent, sibling, or blocking tasks\n- **People** \u2014 link assignees or stakeholders when mentioning them\n- **Conversations** \u2014 link a chat or message range as context\n\n### Why this matters\n\nOther agents and humans read your output. References build a navigable context graph \u2014\nin multi-agent workflows, your references are the map that the next agent follows.";
 export type PreparedLocalImage = {
     attachmentId: string;
     fileName: string;

package/dist/prompt-fragments.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"prompt-fragments.d.ts","sourceRoot":"","sources":["../src/prompt-fragments.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAuBD,wBAAgB,aAAa,CAAC,KAAK,CAAC,EAAE,aAAa,GAAG,MAAM,CAgB3D;AAED,0FAA0F;AAC1F,eAAO,MAAM,aAAa,mcAAqB,CAAC;AAEhD,eAAO,MAAM,aAAa,yhFA+CmC,CAAC;AAE9D,eAAO,MAAM,oBAAoB,23IAuGkD,CAAC;AAEpF,MAAM,MAAM,kBAAkB,GAAG;IAC/B,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,qBAAqB,GAAG;IAClC,MAAM,EAAE,kBAAkB,EAAE,CAAC;IAC7B,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB,CAAC;AAEF,wBAAgB,4BAA4B,CAAC,OAAO,EAAE,qBAAqB,GAAG,MAAM,CAmBnF;AASD,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAIjD"}
+{"version":3,"file":"prompt-fragments.d.ts","sourceRoot":"","sources":["../src/prompt-fragments.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAuBD,wBAAgB,aAAa,CAAC,KAAK,CAAC,EAAE,aAAa,GAAG,MAAM,CAgB3D;AAED,0FAA0F;AAC1F,eAAO,MAAM,aAAa,mcAAqB,CAAC;AAEhD,eAAO,MAAM,aAAa,yhFA+CmC,CAAC;AAE9D,eAAO,MAAM,oBAAoB,msJAyGkD,CAAC;AAEpF,MAAM,MAAM,kBAAkB,GAAG;IAC/B,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,qBAAqB,GAAG;IAClC,MAAM,EAAE,kBAAkB,EAAE,CAAC;IAC7B,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB,CAAC;AAEF,wBAAgB,4BAA4B,CAAC,OAAO,EAAE,qBAAqB,GAAG,MAAM,CAmBnF;AASD,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAIjD"}

package/dist/prompt-fragments.js

@@ -184,6 +184,8 @@ Or upload first and reuse across chats:
     parall messages send prll://cht_aaa --attachment att_yyy --text "Report"
     parall messages send prll://cht_bbb --attachment att_yyy --text "FYI"
 
+The \`--text\` captions above are safe short literals. For message text containing \`$\`, backticks, or quotes, pass it via \`--text-file <path>\` (write the file first, or a quoted heredoc \`--text-file - <<'EOF'\`) instead of \`--text "..."\` — inside double quotes the shell turns \`$1,000\` into \`,000\` and executes \`$(...)\`.
+
 ### When to reference
 
 - **Origin** — always link the message or task that triggered your work

package/dist/skills/parall-platform.d.ts

@@ -1,2 +1,2 @@
-export declare const PARALL_PLATFORM_SKILL = "# Parall Platform\n\nQuery organization data via the Parall CLI. Auth is pre-configured.\n\n## Identity\n\n```bash\nparall whoami\n```\n\n## Members & Agents\n\n```bash\nparall members list          # All org members (humans + agents)\nparall agents list           # Agents only\nparall users get prll://usr_xxx     # Get user details by ID\n```\n\nCreate a hosted agent when the user asks for a Parall-managed runtime. Hosted\nprovisioning is asynchronous: creation means the agent identity, API key, and\nmachine record were accepted, not that the runtime is online yet. Use `--wait`\nto wait until the machine reaches `running`, and use `--wait-online` when the\ntask requires the child agent to be connected before you report completion.\nFor hosted agents, use `--discard-api-key`; the server injects the one-time key\ninto the hosted runtime, so the parent agent must not print or persist it.\n\nCreate a self-hosted agent only when the runtime will be connected outside\nParall-managed compute. In that case, write the one-time `api_key` to\n`--api-key-file` so it is not captured in tool-result logs. Treat `api_key` as a\nsecret: do not print, read aloud, post it in shared chats, or echo the file\ncontents. Include the `user.id` in normal responses, and pass the key file only\nthrough an explicit secure runtime handoff when connection is required. Never\nuse `--show-api-key` from an agent runtime. Agent callers cannot set provider\noverrides until the dedicated fine-grained permission flow lands.\n\n```bash\n# Hosted runtime (Parall-managed compute)\nparall agents create \\\n  --name \"Research Agent\" \\\n  --runtime-type codex \\\n  --machine-type cloud \\\n  --machine-label standard \\\n  --discard-api-key \\\n  --wait \\\n  --wait-online\n\n# Self-hosted runtime\nparall agents create --name \"Research Agent\" --runtime-type codex --api-key-file /tmp/research-agent.api-key\n```\n\nInspect hosted provisioning directly when a create command returns before the\nruntime is online, or when you need logs for a failed machine. If `agents create`\nexits non-zero after creating a hosted agent, read the printed `user.id` and\n`machine.id`, then use these commands to decide whether to wait, inspect logs,\nor report the failed machine for retry.\n\n```bash\nparall machines status prll://mch_xxx\nparall machines logs prll://mch_xxx --lines 100\n```\n\n## Chats & Messages\n\n```bash\nparall chats list            # List all chats\nparall messages list prll://cht_xxx # Read chat message history\nparall messages list prll://cht_xxx --since 2026-01-01 # Only messages at/after a date (RFC3339 or YYYY-MM-DD)\n```\n\n## Org-Context Search\n\nBefore deciding or starting non-trivial work, search the org's real history \u2014\npast discussions, decisions, tasks, and wiki notes \u2014 so you don't re-litigate\nsettled questions or repeat known mistakes. This searches live org data\n(semantic + keyword), not a local copy, and is permission-filtered to what you\ncan see.\n\n```bash\n# Semantic + keyword search across messages, tasks, and wiki\nparall search \"auth v5 upgrade\"\n\n# Restrict entity types (m=message, t=task, w=wiki). --channel narrows the\n# MESSAGE hits to one chat (tasks/wiki are unaffected by it).\nparall search \"auth v5 upgrade\" --types m,w --channel prll://cht_eng\n\n# Time-box to recent activity (RFC3339 or YYYY-MM-DD). Narrows messages + tasks;\n# wiki is always matched by relevance (the index has no authored timestamp).\nparall search \"auth v5 upgrade\" --since 2026-01-01\n\n# Narrow wiki hits to a frontmatter document type\nparall search \"deploy steps\" --types w --wiki-type Runbook\n```\n\nEven with zero curated notes, the raw message + task history is searchable \u2014 the\noriginal discussion and its approval/rejection IS the precedent.\n\n## Sending Messages\n\nEach `[Event: message.new]` includes `[Chat: ... (prll://cht_xxx)]` \u2014 use that chat URI to reply.\n\n```bash\n# Reply to a chat (use the chat URI from the event)\nparall messages send prll://cht_xxx --text \"Your reply\"\n\n# Direct message by user URI or display name\nparall dm prll://usr_xxx --text \"Hello\"\nparall dm \"Alice\" --text \"Hello\"\n\n# Thread reply\nparall messages send prll://cht_xxx --text \"Reply\" --thread-root-id 01JWC...\n\n# FYI message (no response expected \u2014 the recipient sees `[Hint: no_reply]`)\nparall messages send prll://cht_xxx --text \"FYI: done\" --no-reply\n\n# Silence this turn entirely \u2014 no chat message produced. Use when you receive\n# `[Hint: no_reply]` or otherwise decide the turn needs no visible reply.\n# Run BEFORE any `messages send` / `dm`; those still deliver real messages.\nparall no-reply --reason \"ack only, nothing to add\"\n```\n\n## Files & Attachments\n\nAttachments appear in events as `[Attachment: prll://att_xxx | mime | size | name]`.\n\n```bash\n# Download an attachment\nparall files download att_xxx --output /tmp/file.png\n\n# Upload a file (returns attachment_id)\nparall files upload /tmp/report.pdf\n\n# Send a message with a file\nparall messages send prll://cht_xxx --file /tmp/output.png --text \"Done\"\n\n# Send an existing attachment to another chat\nparall messages send prll://cht_xxx --attachment att_xxx --text \"See attached\"\n\n# DM with a file\nparall dm \"Alice\" --file /tmp/report.pdf --text \"Report attached\"\n```\n\n`--file` and `--attachment` are mutually exclusive. `--text` can be combined with either.\n\n## Approvals\n\nWhen a CLI command returns a `PERMISSION_DENIED` error, the output includes the denied `action` and `resource_uri`. Whether that action can be approved is decided by the server (there is no fixed allowlist):\n- If it IS approvable, a `Request approval:` line with a `parall approvals request` command follows \u2014 fill in the placeholders it shows (`--chat`, `--title`, `--reason`) and run it.\n- If it is NOT approvable, the output says so \u2014 ask a human with permission instead of requesting approval.\n\nA different `INVALID_TARGET` error means you addressed the wrong kind of thing (e.g. a `usr_` id where a chat is expected). Follow the message (e.g. use `parall dm` to message a user) \u2014 do not request approval for it.\n\n```bash\n# Request approval (use action and resource_uri from the error)\nparall approvals request --action chat.archive --resource prll://cht_xxx --chat prll://cht_yyy --title \"Archive old channel\" --reason \"No activity in 6 months\"\n\n# Check a specific approval's status\nparall approvals get prll://apr_xxx\n\n# Wait for a decision (blocks until approved/rejected/timeout)\nparall approvals wait prll://apr_xxx --timeout 300\n\n# List all your pending approvals\nparall approvals list\n\n# List available approvable actions\nparall approvals actions\n\n# Cancel a pending request you made\nparall approvals cancel prll://apr_xxx\n```\n\nOnly request approval after receiving an actual `PERMISSION_DENIED` error \u2014 never preemptively. The `--chat` flag specifies where the approval card appears; use the chat where the conversation is happening.\n\n## Reference URIs\n\nEvery entity is addressable with a `prll://` URI. Common prefixes you'll see in events, messages, and schedule descriptions:\n\n| Prefix | Entity | Skill |\n|--------|--------|-------|\n| `prll://usr_` | User (human or agent) | parall-platform |\n| `prll://cht_` | Chat | parall-platform |\n| `prll://msg_` | Message | parall-platform |\n| `prll://tsk_` | Task | parall-tasks |\n| `prll://prj_` | Project | parall-tasks |\n| `prll://sch_` | Schedule (time trigger) | parall-schedules |\n| `prll://srn_` | Schedule run (single fire audit record; carries fire-time snapshot) | parall-schedules |\n| `prll://xcn_` | External Trigger Connection (incoming endpoint) | parall-external-triggers |\n| `prll://xin_` | External Trigger Event (single incoming event audit record) | parall-external-triggers |\n| `prll://xtr_` | External Trigger (incoming trigger configuration) | parall-external-triggers |\n| `prll://xrn_` | External Trigger run (single matched dispatch audit record) | parall-external-triggers |\n| `prll://wik_` | Wiki | parall-wiki |\n| `prll://att_` | Attachment | parall-platform (files) |\n\nWhen a message or event references `prll://sch_xxx` or `prll://srn_xxx`, or when you receive `[Event: schedule.fired]`, switch to the **parall-schedules** skill for the CLI commands (create / list / pause / resume / cancel / runs).\n\nWhen a message or event references `prll://xcn_xxx`, `prll://xin_xxx`, `prll://xtr_xxx`, or `prll://xrn_xxx`, or when you receive `[Event: external.trigger]`, switch to the **parall-external-triggers** skill for the CLI commands (connections / triggers / events / runs).\n\n## References (relationship graph)\n\n`prll://` references between entities form a graph \u2014 a message cites a task, a\ntask cites a wiki page, and so on. Walk it to answer \"what is this decision /\nentity connected to\". All results are permission-filtered to what you can see.\n\n```bash\n# Resolve URIs to entity metadata (titles, status, previews)\nparall refs resolve prll://tsk_xxx prll://wik_xxx\n\n# Single hop \u2014 who references X\nparall refs backlinks prll://tsk_xxx\n\n# Multi-hop \u2014 the connected sub-graph around X (entity-level URI only \u2014 no\n# path/anchor; depth 1\u20134, default 2)\nparall refs graph prll://tsk_xxx --depth 2\n```\n\n`refs graph` traverses both directions (inbound + outbound) and returns `nodes`\nand `edges` with each node's hop `depth`. `truncated: true` means a size cap clipped\nthe result \u2014 narrow it with a smaller `--depth`.\n\nCLI success output is JSON. Errors print a JSON line (`{\"error\",\"status\",\"code\",...}`) and, on a `PERMISSION_DENIED`, may add a plain-text `Request approval:` line \u2014 read both.\n";
+export declare const PARALL_PLATFORM_SKILL = "# Parall Platform\n\nQuery organization data via the Parall CLI. Auth is pre-configured.\n\n## Identity\n\n```bash\nparall whoami\n```\n\n## Members & Agents\n\n```bash\nparall members list          # All org members (humans + agents)\nparall agents list           # Agents only\nparall users get prll://usr_xxx     # Get user details by ID\n```\n\nCreate a hosted agent when the user asks for a Parall-managed runtime. Hosted\nprovisioning is asynchronous: creation means the agent identity, API key, and\nmachine record were accepted, not that the runtime is online yet. Use `--wait`\nto wait until the machine reaches `running`, and use `--wait-online` when the\ntask requires the child agent to be connected before you report completion.\nFor hosted agents, use `--discard-api-key`; the server injects the one-time key\ninto the hosted runtime, so the parent agent must not print or persist it.\n\nCreate a self-hosted agent only when the runtime will be connected outside\nParall-managed compute. In that case, write the one-time `api_key` to\n`--api-key-file` so it is not captured in tool-result logs. Treat `api_key` as a\nsecret: do not print, read aloud, post it in shared chats, or echo the file\ncontents. Include the `user.id` in normal responses, and pass the key file only\nthrough an explicit secure runtime handoff when connection is required. Never\nuse `--show-api-key` from an agent runtime. Agent callers cannot set provider\noverrides until the dedicated fine-grained permission flow lands.\n\n```bash\n# Hosted runtime (Parall-managed compute)\nparall agents create \\\n  --name \"Research Agent\" \\\n  --runtime-type codex \\\n  --machine-type cloud \\\n  --machine-label standard \\\n  --discard-api-key \\\n  --wait \\\n  --wait-online\n\n# Self-hosted runtime\nparall agents create --name \"Research Agent\" --runtime-type codex --api-key-file /tmp/research-agent.api-key\n```\n\nInspect hosted provisioning directly when a create command returns before the\nruntime is online, or when you need logs for a failed machine. If `agents create`\nexits non-zero after creating a hosted agent, read the printed `user.id` and\n`machine.id`, then use these commands to decide whether to wait, inspect logs,\nor report the failed machine for retry.\n\n```bash\nparall machines status prll://mch_xxx\nparall machines logs prll://mch_xxx --lines 100\n```\n\n## Chats & Messages\n\n```bash\nparall chats list            # List all chats\nparall messages list prll://cht_xxx # Read chat message history\nparall messages list prll://cht_xxx --since 2026-01-01 # Only messages at/after a date (RFC3339 or YYYY-MM-DD)\n```\n\n## Org-Context Search\n\nBefore deciding or starting non-trivial work, search the org's real history \u2014\npast discussions, decisions, tasks, and wiki notes \u2014 so you don't re-litigate\nsettled questions or repeat known mistakes. This searches live org data\n(semantic + keyword), not a local copy, and is permission-filtered to what you\ncan see.\n\n```bash\n# Semantic + keyword search across messages, tasks, and wiki\nparall search \"auth v5 upgrade\"\n\n# Restrict entity types (m=message, t=task, w=wiki). --channel narrows the\n# MESSAGE hits to one chat (tasks/wiki are unaffected by it).\nparall search \"auth v5 upgrade\" --types m,w --channel prll://cht_eng\n\n# Time-box to recent activity (RFC3339 or YYYY-MM-DD). Narrows messages + tasks;\n# wiki is always matched by relevance (the index has no authored timestamp).\nparall search \"auth v5 upgrade\" --since 2026-01-01\n\n# Narrow wiki hits to a frontmatter document type\nparall search \"deploy steps\" --types w --wiki-type Runbook\n```\n\nEven with zero curated notes, the raw message + task history is searchable \u2014 the\noriginal discussion and its approval/rejection IS the precedent.\n\n## Sending Messages\n\nEach `[Event: message.new]` includes `[Chat: ... (prll://cht_xxx)]` \u2014 use that chat URI to reply.\n\n> **How you pass the message body matters \u2014 your command runs through a shell.**\n> Inside double quotes the shell expands `$`, backticks, and `$(...)` *before*\n> the CLI sees them: `--text \"That costs $1,000\"` sends `That costs ,000`, and\n> `--text \"$(cmd)\"` runs `cmd`. Single quotes instead break on apostrophes\n> (`I'm`, `don't`). So do **not** wrap real message content in quotes \u2014 pass it\n> through `--text-file` (a written file, or a quoted heredoc `<<'EOF'` that\n> disables all expansion). Reserve `--text \"...\"` for short literals with no\n> `$`, backtick, or apostrophe.\n\n```bash\n# One-off reply \u2192 quoted heredoc into stdin. The quoted delimiter <<'EOF'\n# disables ALL shell expansion, so $, backticks and apostrophes pass verbatim.\nparall messages send prll://cht_xxx --text-file - <<'PARALL_EOF'\nSure \u2014 that's $1,000, and $(whoami) stays literal. I'm on it.\nPARALL_EOF\n\n# Longer / multi-line reply \u2192 write it with your file tool (no shell touches\n# the body), then point --text-file at the file.\nparall messages send prll://cht_xxx --text-file /tmp/reply.md\n\n# Short literal with no $, backtick, or apostrophe \u2192 --text is fine.\nparall messages send prll://cht_xxx --text \"On it\"\n\n# Direct message by user URI or display name (same --text-file / heredoc rules)\nparall dm prll://usr_xxx --text-file /tmp/reply.md\nparall dm \"Alice\" --text \"Hello\"\n\n# Thread reply\nparall messages send prll://cht_xxx --text-file /tmp/reply.md --thread-root-id 01JWC...\n\n# FYI message (no response expected \u2014 the recipient sees `[Hint: no_reply]`)\nparall messages send prll://cht_xxx --text \"FYI: done\" --no-reply\n\n# Silence this turn entirely \u2014 no chat message produced. Use when you receive\n# `[Hint: no_reply]` or otherwise decide the turn needs no visible reply.\n# Run BEFORE any `messages send` / `dm`; those still deliver real messages.\nparall no-reply --reason \"ack only, nothing to add\"\n```\n\n## Files & Attachments\n\nAttachments appear in events as `[Attachment: prll://att_xxx | mime | size | name]`.\n\n```bash\n# Download an attachment\nparall files download att_xxx --output /tmp/file.png\n\n# Upload a file (returns attachment_id)\nparall files upload /tmp/report.pdf\n\n# Send a message with a file\nparall messages send prll://cht_xxx --file /tmp/output.png --text \"Done\"\n\n# Send an existing attachment to another chat\nparall messages send prll://cht_xxx --attachment att_xxx --text \"See attached\"\n\n# DM with a file\nparall dm \"Alice\" --file /tmp/report.pdf --text \"Report attached\"\n```\n\n`--file` and `--attachment` are mutually exclusive. A caption (`--text` for\nshort literals, or `--text-file` for anything with `$`, backticks, or quotes)\ncan be combined with either.\n\n## Approvals\n\nWhen a CLI command returns a `PERMISSION_DENIED` error, the output includes the denied `action` and `resource_uri`. Whether that action can be approved is decided by the server (there is no fixed allowlist):\n- If it IS approvable, a `Request approval:` line with a `parall approvals request` command follows \u2014 fill in the placeholders it shows (`--chat`, `--title`, `--reason`) and run it.\n- If it is NOT approvable, the output says so \u2014 ask a human with permission instead of requesting approval.\n\nA different `INVALID_TARGET` error means you addressed the wrong kind of thing (e.g. a `usr_` id where a chat is expected). Follow the message (e.g. use `parall dm` to message a user) \u2014 do not request approval for it.\n\n```bash\n# Request approval (use action and resource_uri from the error)\nparall approvals request --action chat.archive --resource prll://cht_xxx --chat prll://cht_yyy --title \"Archive old channel\" --reason \"No activity in 6 months\"\n\n# Check a specific approval's status\nparall approvals get prll://apr_xxx\n\n# Wait for a decision (blocks until approved/rejected/timeout)\nparall approvals wait prll://apr_xxx --timeout 300\n\n# List all your pending approvals\nparall approvals list\n\n# List available approvable actions\nparall approvals actions\n\n# Cancel a pending request you made\nparall approvals cancel prll://apr_xxx\n```\n\nOnly request approval after receiving an actual `PERMISSION_DENIED` error \u2014 never preemptively. The `--chat` flag specifies where the approval card appears; use the chat where the conversation is happening.\n\n## Reference URIs\n\nEvery entity is addressable with a `prll://` URI. Common prefixes you'll see in events, messages, and schedule descriptions:\n\n| Prefix | Entity | Skill |\n|--------|--------|-------|\n| `prll://usr_` | User (human or agent) | parall-platform |\n| `prll://cht_` | Chat | parall-platform |\n| `prll://msg_` | Message | parall-platform |\n| `prll://tsk_` | Task | parall-tasks |\n| `prll://prj_` | Project | parall-tasks |\n| `prll://sch_` | Schedule (time trigger) | parall-schedules |\n| `prll://srn_` | Schedule run (single fire audit record; carries fire-time snapshot) | parall-schedules |\n| `prll://xcn_` | External Trigger Connection (incoming endpoint) | parall-external-triggers |\n| `prll://xin_` | External Trigger Event (single incoming event audit record) | parall-external-triggers |\n| `prll://xtr_` | External Trigger (incoming trigger configuration) | parall-external-triggers |\n| `prll://xrn_` | External Trigger run (single matched dispatch audit record) | parall-external-triggers |\n| `prll://wik_` | Wiki | parall-wiki |\n| `prll://att_` | Attachment | parall-platform (files) |\n\nWhen a message or event references `prll://sch_xxx` or `prll://srn_xxx`, or when you receive `[Event: schedule.fired]`, switch to the **parall-schedules** skill for the CLI commands (create / list / pause / resume / cancel / runs).\n\nWhen a message or event references `prll://xcn_xxx`, `prll://xin_xxx`, `prll://xtr_xxx`, or `prll://xrn_xxx`, or when you receive `[Event: external.trigger]`, switch to the **parall-external-triggers** skill for the CLI commands (connections / triggers / events / runs).\n\n## References (relationship graph)\n\n`prll://` references between entities form a graph \u2014 a message cites a task, a\ntask cites a wiki page, and so on. Walk it to answer \"what is this decision /\nentity connected to\". All results are permission-filtered to what you can see.\n\n```bash\n# Resolve URIs to entity metadata (titles, status, previews)\nparall refs resolve prll://tsk_xxx prll://wik_xxx\n\n# Single hop \u2014 who references X\nparall refs backlinks prll://tsk_xxx\n\n# Multi-hop \u2014 the connected sub-graph around X (entity-level URI only \u2014 no\n# path/anchor; depth 1\u20134, default 2)\nparall refs graph prll://tsk_xxx --depth 2\n```\n\n`refs graph` traverses both directions (inbound + outbound) and returns `nodes`\nand `edges` with each node's hop `depth`. `truncated: true` means a size cap clipped\nthe result \u2014 narrow it with a smaller `--depth`.\n\nCLI success output is JSON. Errors print a JSON line (`{\"error\",\"status\",\"code\",...}`) and, on a `PERMISSION_DENIED`, may add a plain-text `Request approval:` line \u2014 read both.\n";
 //# sourceMappingURL=parall-platform.d.ts.map

package/dist/skills/parall-platform.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"parall-platform.d.ts","sourceRoot":"","sources":["../../src/skills/parall-platform.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,qBAAqB,4jTA4NjC,CAAC"}
+{"version":3,"file":"parall-platform.d.ts","sourceRoot":"","sources":["../../src/skills/parall-platform.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,qBAAqB,wzVAiPjC,CAAC"}