@parall/agent-core 1.36.0 → 1.37.0

package/src/platform-config.ts

@@ -6,6 +6,11 @@ import type { GatewayLogger } from './dispatch-adapter.js';
 export interface PlatformDefaults {
   model: string | null;
   thinkingEffort: string | null;
+  // Optional so adding it didn't break existing constructors of this exported
+  // type. Absent/undefined = old server didn't send model_is_pin → fall back to
+  // model_management; true = operator PIN (override, beats env); false = catalog
+  // FLOOR (loses to env).
+  modelIsPin?: boolean;
 }
 
 export interface PlatformConfigManager {
@@ -19,6 +24,12 @@ export interface PlatformManagementProfile {
   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 function isPlatformManagedProfile(
   profile: PlatformManagementProfile | null | undefined,
 ): boolean {
@@ -34,6 +45,10 @@ export function isPlatformManagedProfile(
  * 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: PlatformManagementProfile | null | undefined,
@@ -64,6 +79,19 @@ export function resolveRuntimeModel(
   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: PlatformDefaults,
+  profile: PlatformManagementProfile | null | undefined,
+): boolean {
+  return defaults.modelIsPin !== undefined ? defaults.modelIsPin : isPlatformModelOverride(profile);
+}
+
 interface PlatformModelDef {
   id?: unknown;
   runtime_names?: unknown;
@@ -72,6 +100,9 @@ interface PlatformModelDef {
 interface CachedPlatformConfig {
   version: string;
   config: Record<string, unknown>;
+  // Top-level sibling of `config` (model_is_pin lives on the response, not inside
+  // config). Old cache files lack it → undefined → bridge falls back.
+  modelIsPin?: boolean;
   fetchedAt: string;
 }
 
@@ -95,6 +126,7 @@ function saveCache(stateDir: string, response: PlatformConfigResponse): void {
   const cached: CachedPlatformConfig = {
     version: response.version,
     config: response.config,
+    modelIsPin: response.model_is_pin,
     fetchedAt: new Date().toISOString(),
   };
   const filePath = cachePath(stateDir);
@@ -110,25 +142,49 @@ function runtimeModelName(
   config: Record<string, unknown>,
 ): string | null {
   const runtime = runtimeType?.trim();
-  if (!runtime || runtime === 'openclaw') return canonicalModel;
+  if (!runtime || runtime === 'openclaw' || runtime === 'hermes') return canonicalModel;
 
   const models = (config.models ?? {}) as Record<string, unknown>;
   const providers = (models.providers ?? {}) as Record<string, unknown>;
   const parall = (providers.parall ?? {}) as Record<string, unknown>;
   const catalog = Array.isArray(parall.models) ? (parall.models as PlatformModelDef[]) : [];
   const match = catalog.find((model) => model.id === canonicalModel);
-  const runtimeNames = (match?.runtime_names ?? {}) as Record<string, unknown>;
+  // Unknown to the catalog: let the bridge fall back to env/default.
+  if (!match) return null;
+  const runtimeNames = (match.runtime_names ?? {}) as Record<string, unknown>;
   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: Record<string, unknown>, runtimeType?: string): PlatformDefaults {
+// 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: Record<string, unknown>,
+  runtimeType: string | undefined,
+): Omit<PlatformDefaults, 'modelIsPin'> {
   const agents = (config.agents ?? {}) as Record<string, unknown>;
   const defaults = (agents.defaults ?? {}) as Record<string, unknown>;
 
   let model: string | null = 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);
   }
 
@@ -148,14 +204,31 @@ export function createPlatformConfigManager(opts: {
 }): PlatformConfigManager {
   const { client, stateDir, runtimeType, log } = opts;
   let cachedVersion: string | undefined;
-  let currentDefaults: PlatformDefaults = { model: null, thinkingEffort: null };
+  let currentDefaults: PlatformDefaults = {
+    model: null,
+    thinkingEffort: null,
+    modelIsPin: undefined,
+  };
   let currentRawConfig: Record<string, unknown> | null = 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 {
@@ -189,7 +262,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;
     },
 

package/src/prompt-fragments.ts

@@ -199,6 +199,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/src/skills/parall-platform.ts

@@ -64,22 +64,69 @@ parall machines logs prll://mch_xxx --lines 100
 \`\`\`bash
 parall chats list            # List all chats
 parall messages list prll://cht_xxx # Read chat message history
+parall messages list prll://cht_xxx --since 2026-01-01 # Only messages at/after a date (RFC3339 or YYYY-MM-DD)
 \`\`\`
 
+## Org-Context Search
+
+Before deciding or starting non-trivial work, search the org's real history —
+past discussions, decisions, tasks, and wiki notes — so you don't re-litigate
+settled questions or repeat known mistakes. This searches live org data
+(semantic + keyword), not a local copy, and is permission-filtered to what you
+can see.
+
+\`\`\`bash
+# Semantic + keyword search across messages, tasks, and wiki
+parall search "auth v5 upgrade"
+
+# Restrict entity types (m=message, t=task, w=wiki). --channel narrows the
+# MESSAGE hits to one chat (tasks/wiki are unaffected by it).
+parall search "auth v5 upgrade" --types m,w --channel prll://cht_eng
+
+# Time-box to recent activity (RFC3339 or YYYY-MM-DD). Narrows messages + tasks;
+# wiki is always matched by relevance (the index has no authored timestamp).
+parall search "auth v5 upgrade" --since 2026-01-01
+
+# Narrow wiki hits to a frontmatter document type
+parall search "deploy steps" --types w --wiki-type Runbook
+\`\`\`
+
+Even with zero curated notes, the raw message + task history is searchable — the
+original discussion and its approval/rejection IS the precedent.
+
 ## Sending Messages
 
 Each \`[Event: message.new]\` includes \`[Chat: ... (prll://cht_xxx)]\` — use that chat URI to reply.
 
+> **How you pass the message body matters — your command runs through a shell.**
+> Inside double quotes the shell expands \`$\`, backticks, and \`$(...)\` *before*
+> the CLI sees them: \`--text "That costs $1,000"\` sends \`That costs ,000\`, and
+> \`--text "$(cmd)"\` runs \`cmd\`. Single quotes instead break on apostrophes
+> (\`I'm\`, \`don't\`). So do **not** wrap real message content in quotes — pass it
+> through \`--text-file\` (a written file, or a quoted heredoc \`<<'EOF'\` that
+> disables all expansion). Reserve \`--text "..."\` for short literals with no
+> \`$\`, backtick, or apostrophe.
+
 \`\`\`bash
-# Reply to a chat (use the chat URI from the event)
-parall messages send prll://cht_xxx --text "Your reply"
+# One-off reply → quoted heredoc into stdin. The quoted delimiter <<'EOF'
+# disables ALL shell expansion, so $, backticks and apostrophes pass verbatim.
+parall messages send prll://cht_xxx --text-file - <<'PARALL_EOF'
+Sure — that's $1,000, and $(whoami) stays literal. I'm on it.
+PARALL_EOF
 
-# Direct message by user URI or display name
-parall dm prll://usr_xxx --text "Hello"
+# Longer / multi-line reply → write it with your file tool (no shell touches
+# the body), then point --text-file at the file.
+parall messages send prll://cht_xxx --text-file /tmp/reply.md
+
+# Short literal with no $, backtick, or apostrophe → --text is fine.
+parall messages send prll://cht_xxx --text "On it"
+
+# Direct message by user URI or display name (same --text-file / heredoc rules)
+parall dm prll://usr_xxx --text-file /tmp/reply.md
 parall dm "Alice" --text "Hello"
 
 # Thread reply
-parall messages send prll://cht_xxx --text "Reply" --thread-root-id 01JWC...
+parall messages send prll://cht_xxx --text-file /tmp/reply.md --thread-root-id 01JWC...
 
 # FYI message (no response expected — the recipient sees \`[Hint: no_reply]\`)
 parall messages send prll://cht_xxx --text "FYI: done" --no-reply
@@ -111,7 +158,9 @@ parall messages send prll://cht_xxx --attachment att_xxx --text "See attached"
 parall dm "Alice" --file /tmp/report.pdf --text "Report attached"
 \`\`\`
 
-\`--file\` and \`--attachment\` are mutually exclusive. \`--text\` can be combined with either.
+\`--file\` and \`--attachment\` are mutually exclusive. A caption (\`--text\` for
+short literals, or \`--text-file\` for anything with \`$\`, backticks, or quotes)
+can be combined with either.
 
 ## Approvals
 
@@ -167,5 +216,27 @@ When a message or event references \`prll://sch_xxx\` or \`prll://srn_xxx\`, or
 
 When 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).
 
+## References (relationship graph)
+
+\`prll://\` references between entities form a graph — a message cites a task, a
+task cites a wiki page, and so on. Walk it to answer "what is this decision /
+entity connected to". All results are permission-filtered to what you can see.
+
+\`\`\`bash
+# Resolve URIs to entity metadata (titles, status, previews)
+parall refs resolve prll://tsk_xxx prll://wik_xxx
+
+# Single hop — who references X
+parall refs backlinks prll://tsk_xxx
+
+# Multi-hop — the connected sub-graph around X (entity-level URI only — no
+# path/anchor; depth 1–4, default 2)
+parall refs graph prll://tsk_xxx --depth 2
+\`\`\`
+
+\`refs graph\` traverses both directions (inbound + outbound) and returns \`nodes\`
+and \`edges\` with each node's hop \`depth\`. \`truncated: true\` means a size cap clipped
+the result — narrow it with a smaller \`--depth\`.
+
 CLI 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 — read both.
 `;

package/src/types.ts

@@ -31,6 +31,7 @@ export type ParallEvent = {
     | 'wiki_comment'
     | 'schedule'
     | 'external_trigger'
+    | 'channel_message'
     | 'approval';
   targetId: string;
   targetName?: string;
@@ -65,10 +66,23 @@ export type ParallEvent = {
   externalConnectionDisplayName?: string;
   externalIngressEventId?: string;
   externalIngressEventType?: string;
+  /** External IM channel metadata, used for channel_message events. */
+  channelProvider?: string;
+  channelConversationType?: string;
+  /** Provider-side conversation id (the send_message target). */
+  channelExternalConversationId?: string;
+  /** Provider-side message id (in-thread reply target). */
+  channelExternalMessageId?: string;
   /** Original event timestamp (e.g., message.created_at). When present,
    *  input steps use this instead of server insertion time for ordering. */
   sentAt?: string;
-  ackSourceType?: 'message' | 'task_activity' | 'comment' | 'schedule_run' | 'external_trigger_run';
+  ackSourceType?:
+    | 'message'
+    | 'task_activity'
+    | 'comment'
+    | 'schedule_run'
+    | 'external_trigger_run'
+    | 'channel_message';
   ackSourceId?: string;
   /** Unread message count in the target chat since agent's last interaction. */
   unreadCount?: number;