@parall/agent-core 1.31.0 → 1.32.1

package/src/prompt-fragments.ts

@@ -27,29 +27,32 @@ be direct, and care about the outcome of the work — not just the request in fr
 of you.`;
 
 function sanitizeProfileField(value: string): string {
-  return value.replace(/[\r\n]+/g, " ").replace(/`/g, "'").trim();
+  return value
+    .replace(/[\r\n]+/g, ' ')
+    .replace(/`/g, "'")
+    .trim();
 }
 
 function sanitizeProfileBlock(value: string): string {
-  return value.replace(/\r\n?/g, "\n").trim();
+  return value.replace(/\r\n?/g, '\n').trim();
 }
 
 export function buildIdentity(agent?: AgentIdentity): string {
   if (!agent) return PRLL_IDENTITY_BASE;
   const name = sanitizeProfileField(agent.displayName);
-  const lines = [PRLL_IDENTITY_BASE, "", "### Your Parall Identity", ""];
+  const lines = [PRLL_IDENTITY_BASE, '', '### Your Parall Identity', ''];
   lines.push(`You are **${name}** (\`prll://${agent.userId}\`).`);
   if (agent.description) {
     const description = sanitizeProfileBlock(agent.description);
     if (description) {
-      lines.push("", "### Your Agent Profile", "", description);
+      lines.push('', '### Your Agent Profile', '', description);
     }
   }
   lines.push(
-    "",
+    '',
     `When you see \`${agent.userId}\` or \`prll://${agent.userId}\` in messages, mentions, or events — that's you.`,
   );
-  return lines.join("\n");
+  return lines.join('\n');
 }
 
 /** @deprecated Use buildIdentity() instead. Kept for backward compat during migration. */
@@ -90,10 +93,15 @@ Other agents share this workspace. Before starting work, check whether someone
 ### Permissions and approvals
 You have real permissions based on your roles (chat member/admin, org member).
 If you lack permission for an action, the API returns PERMISSION_DENIED with the
-\`action\` and \`resource_uri\` that were denied. When that happens, use
-\`approvals request\` to ask someone with permission to approve it — don't retry
-or work around the denial. Only request approval after an actual denial, never
-preemptively.
+\`action\` and \`resource_uri\` that were denied. The server decides whether that
+action is approvable: if it is, the CLI prints an \`approvals request\` command —
+fill in the placeholders it shows (\`--chat\`, \`--title\`, \`--reason\`) and run
+it to ask someone with permission. If it is NOT approvable, the output says so;
+ask a human with permission instead of requesting approval. A
+\`INVALID_TARGET\` error instead means you addressed the wrong kind of thing
+(e.g. a \`usr_\` id where a chat is expected) — follow the message (e.g. use
+\`dm\` for a user). Don't retry or work around a denial; only request approval
+after an actual denial, never preemptively.
 
 ### When in doubt
 Prefer asking over guessing. Prefer "I don't know" over fabricating. Your
@@ -143,6 +151,18 @@ resolves and renders the entity title automatically.
 
     prll://tsk_xxx/description#Implementation     heading within task description
 
+### Unread context
+
+When dispatched to a chat, you may see \`[Unread: N messages | since: prll://msg_xxx]\`.
+This shows messages since your last interaction — your read cursor advances after each
+dispatch, so context you skip now won't appear as unread next time. Use
+\`parall messages list <chat> --limit 20\` to fetch recent context. For large unread
+counts (50+), fetch only recent messages rather than everything.
+
+Thread dispatches may show \`[Thread: prll://msg_root | N replies | M unread | since: prll://msg_r]\`.
+Same semantics — use \`parall messages list <chat> --thread-root-id <thread_root> --limit 20\` to
+catch up on the thread.
+
 ### Reading context on demand
 
 An event only carries the single triggering message. If you're mentioned in a
@@ -206,7 +226,7 @@ export type LocalAttachmentResult = {
 };
 
 export function renderLocalAttachmentSection(section: LocalAttachmentResult): string {
-  if (section.images.length === 0 && section.notes.length === 0) return "";
+  if (section.images.length === 0 && section.notes.length === 0) return '';
 
   // Each image renders as a metadata header line plus the absolute path on
   // its own line. The path stands alone (no quoting / escaping) so file-
@@ -215,7 +235,7 @@ export function renderLocalAttachmentSection(section: LocalAttachmentResult): st
   // the bridge operator. A pathological workspace dir with embedded newlines
   // would split across lines; that's exotic enough not to warrant scrubbing
   // every consumer's path through escape rules.
-  const lines = ["[Local attachment files]"];
+  const lines = ['[Local attachment files]'];
   for (const image of section.images) {
     lines.push(
       `- prll://${image.attachmentId} (${sanitizePromptMeta(image.mimeType)}, ${formatBytes(image.fileSize)}, ${sanitizePromptMeta(image.fileName)})`,
@@ -223,11 +243,14 @@ export function renderLocalAttachmentSection(section: LocalAttachmentResult): st
     );
   }
   lines.push(...section.notes);
-  return lines.join("\n");
+  return lines.join('\n');
 }
 
 function sanitizePromptMeta(value: string): string {
-  return value.replace(/[\r\n]+/g, " ").replace(/[()]/g, " ").trim();
+  return value
+    .replace(/[\r\n]+/g, ' ')
+    .replace(/[()]/g, ' ')
+    .trim();
 }
 
 export function formatBytes(bytes: number): string {

package/src/provider-config.ts

@@ -7,6 +7,18 @@ export interface ProviderConfig {
 }
 
 export function llmSource(pc?: ProviderConfig): string {
+  return effectiveLLMSourceExplicit(pc) || 'parall';
+}
+
+/**
+ * Returns the explicitly-configured LLM source — the llm_source value when
+ * set, or "custom" when BYO provider credentials are present — or "" when the
+ * provider_config carries no source signal at all (e.g. the empty `{}` default
+ * that self-hosted agents always have). The daemon supervisor uses the empty
+ * case to defer to the machine-level llm_source instead of letting `{}` shadow
+ * it as "parall". Mirrors the Go `ProviderConfig.EffectiveLLMSourceExplicit`.
+ */
+export function effectiveLLMSourceExplicit(pc?: ProviderConfig): string {
   if (pc?.llm_source) return pc.llm_source;
   if (
     pc?.openai_api_key ||
@@ -14,9 +26,9 @@ export function llmSource(pc?: ProviderConfig): string {
     pc?.anthropic_auth_token ||
     pc?.anthropic_base_url
   ) {
-    return "custom";
+    return 'custom';
   }
-  return "parall";
+  return '';
 }
 
 export function clearAllProviderCreds(env: NodeJS.ProcessEnv): void {

package/src/routing.ts

@@ -1,11 +1,11 @@
-import type { DispatchState, ParallEvent } from "./types.js";
+import type { DispatchState, ParallEvent } from './types.js';
 
 /** Where an inbound event should be routed. */
 export type TriggerDisposition =
-  | { action: "main" }
-  | { action: "buffer-main" }
-  | { action: "buffer-fork"; forkKey: string }
-  | { action: "new-fork" };
+  | { action: 'main' }
+  | { action: 'buffer-main' }
+  | { action: 'buffer-fork'; forkKey: string }
+  | { action: 'new-fork' };
 
 /** Pluggable strategy for routing triggers when main session is busy. */
 export type RoutingStrategy = (event: ParallEvent, state: DispatchState) => TriggerDisposition;
@@ -21,17 +21,17 @@ const MAX_CONCURRENT_FORKS = 20;
  */
 export const defaultRoutingStrategy: RoutingStrategy = (event, state) => {
   if (state.mainCurrentTargetId === event.targetId) {
-    return { action: "buffer-main" };
+    return { action: 'buffer-main' };
   }
 
   const existingForkKey = state.activeForks.get(event.targetId);
-  if (existingForkKey) return { action: "buffer-fork", forkKey: existingForkKey };
+  if (existingForkKey) return { action: 'buffer-fork', forkKey: existingForkKey };
 
   if (state.activeForks.size >= MAX_CONCURRENT_FORKS) {
-    return { action: "buffer-main" };
+    return { action: 'buffer-main' };
   }
 
-  return { action: "new-fork" };
+  return { action: 'new-fork' };
 };
 
 /** Route an inbound event based on current dispatch state. */
@@ -41,7 +41,7 @@ export function routeTrigger(
   strategy: RoutingStrategy = defaultRoutingStrategy,
 ): TriggerDisposition {
   const existingForkKey = state.activeForks.get(event.targetId);
-  if (existingForkKey) return { action: "buffer-fork", forkKey: existingForkKey };
-  if (!state.mainDispatching) return { action: "main" };
+  if (existingForkKey) return { action: 'buffer-fork', forkKey: existingForkKey };
+  if (!state.mainDispatching) return { action: 'main' };
   return strategy(event, state);
 }

package/src/session-state.ts

@@ -67,3 +67,65 @@ export function getDispatchNoReply(sessionKey: string): boolean {
 export function clearDispatchNoReply(sessionKey: string) {
   dispatchNoReplyMap.delete(normalizeSessionKey(sessionKey));
 }
+
+// ---------------------------------------------------------------------------
+// Per-dispatch metrics — populated by runtime adapters, reported by gateway
+// ---------------------------------------------------------------------------
+
+export type DispatchMetrics = {
+  deliver_text_chunks: number;
+  deliver_text_chars: number;
+  message_send_attempts: number;
+  message_send_successes: number;
+  no_reply_called: boolean;
+  tool_call_count: number;
+  started_at: number;
+};
+
+const dispatchMetricsMap = new Map<string, DispatchMetrics>();
+
+export function resetDispatchMetrics(sessionKey: string): void {
+  dispatchMetricsMap.set(normalizeSessionKey(sessionKey), {
+    deliver_text_chunks: 0,
+    deliver_text_chars: 0,
+    message_send_attempts: 0,
+    message_send_successes: 0,
+    no_reply_called: false,
+    tool_call_count: 0,
+    started_at: Date.now(),
+  });
+}
+
+export function getDispatchMetrics(sessionKey: string): DispatchMetrics | undefined {
+  return dispatchMetricsMap.get(normalizeSessionKey(sessionKey));
+}
+
+export function clearDispatchMetrics(sessionKey: string): void {
+  dispatchMetricsMap.delete(normalizeSessionKey(sessionKey));
+}
+
+export function recordDeliverText(sessionKey: string, charCount: number): void {
+  const m = dispatchMetricsMap.get(normalizeSessionKey(sessionKey));
+  if (!m) return;
+  m.deliver_text_chunks++;
+  m.deliver_text_chars += charCount;
+}
+
+export function recordMessageSend(sessionKey: string, success: boolean): void {
+  const m = dispatchMetricsMap.get(normalizeSessionKey(sessionKey));
+  if (!m) return;
+  m.message_send_attempts++;
+  if (success) m.message_send_successes++;
+}
+
+export function recordNoReply(sessionKey: string): void {
+  const m = dispatchMetricsMap.get(normalizeSessionKey(sessionKey));
+  if (!m) return;
+  m.no_reply_called = true;
+}
+
+export function recordToolCall(sessionKey: string): void {
+  const m = dispatchMetricsMap.get(normalizeSessionKey(sessionKey));
+  if (!m) return;
+  m.tool_call_count++;
+}

package/src/skills/index.ts

@@ -1,52 +1,63 @@
-import * as fs from "node:fs";
-import * as path from "node:path";
+import * as fs from 'node:fs';
+import * as path from 'node:path';
 
-export { PARALL_PLATFORM_SKILL } from "./parall-platform.js";
-export { PARALL_TASKS_SKILL } from "./parall-tasks.js";
-export { PARALL_WIKI_SKILL } from "./parall-wiki.js";
-export { PARALL_SCHEDULES_SKILL } from "./parall-schedules.js";
+export { PARALL_PLATFORM_SKILL } from './parall-platform.js';
+export { PARALL_TASKS_SKILL } from './parall-tasks.js';
+export { PARALL_WIKI_SKILL } from './parall-wiki.js';
+export { PARALL_SCHEDULES_SKILL } from './parall-schedules.js';
+export { PARALL_CLIPS_SKILL } from './parall-clips.js';
 
-import { PARALL_PLATFORM_SKILL } from "./parall-platform.js";
-import { PARALL_TASKS_SKILL } from "./parall-tasks.js";
-import { PARALL_WIKI_SKILL } from "./parall-wiki.js";
-import { PARALL_SCHEDULES_SKILL } from "./parall-schedules.js";
+import { PARALL_PLATFORM_SKILL } from './parall-platform.js';
+import { PARALL_TASKS_SKILL } from './parall-tasks.js';
+import { PARALL_WIKI_SKILL } from './parall-wiki.js';
+import { PARALL_SCHEDULES_SKILL } from './parall-schedules.js';
+import { PARALL_CLIPS_SKILL } from './parall-clips.js';
 
 export type SkillMeta = { name: string; description: string; content: string };
 
 export const SKILLS: SkillMeta[] = [
   {
-    name: "parall-platform",
-    description: "Parall platform queries and lightweight agent provisioning: list org members, agents, chats, read message history, check identity, or create another agent. Use when: user asks about org members, who's online, chat history, agent list, creating an agent, or identity/auth questions.",
+    name: 'parall-platform',
+    description:
+      "Parall platform queries and lightweight agent provisioning: list org members, agents, chats, read message history, check identity, or create another agent. Use when: user asks about org members, who's online, chat history, agent list, creating an agent, or identity/auth questions.",
     content: PARALL_PLATFORM_SKILL,
   },
   {
-    name: "parall-tasks",
-    description: "Parall task operations: create, update, comment on, and query tasks and projects. Use when: user asks to create a task, update task status, add comments, list tasks, or manage projects.",
+    name: 'parall-tasks',
+    description:
+      'Parall task operations: create, update, comment on, and query tasks and projects. Use when: user asks to create a task, update task status, add comments, list tasks, or manage projects.',
     content: PARALL_TASKS_SKILL,
   },
   {
-    name: "parall-wiki",
-    description: "Parall wiki operations: read, search, edit, and propose changes to organization knowledge bases. Use when: user asks to read/write docs, edit wiki pages, search knowledge base, propose changes, or review changesets.",
+    name: 'parall-wiki',
+    description:
+      'Parall wiki operations: read, search, edit, and propose changes to organization knowledge bases. Use when: user asks to read/write docs, edit wiki pages, search knowledge base, propose changes, or review changesets.',
     content: PARALL_WIKI_SKILL,
   },
   {
-    name: "parall-schedules",
-    description: "Parall schedule operations: create / pause / resume / cancel recurring or one-shot time triggers; respond to schedule fire events. Use when: user asks to set up a recurring reminder, schedule a delayed prompt, run cron-like work, or when the agent receives an `[Event: schedule.fired]` dispatch.",
+    name: 'parall-schedules',
+    description:
+      'Parall schedule operations: create / pause / resume / cancel recurring or one-shot time triggers; respond to schedule fire events. Use when: user asks to set up a recurring reminder, schedule a delayed prompt, run cron-like work, or when the agent receives an `[Event: schedule.fired]` dispatch.',
     content: PARALL_SCHEDULES_SKILL,
   },
+  {
+    name: 'parall-clips',
+    description:
+      'Parall clip operations: list installed clips, invoke clip commands, inspect clip details. Use when: the task requires external capabilities (GitHub, web search, etc.), user asks about available tools/clips, or you need to call a clip command.',
+    content: PARALL_CLIPS_SKILL,
+  },
 ];
 
 /** Write plain skill markdown files to a target directory (CC/Codex). */
 export function writeSkillFiles(targetDir: string): void {
   fs.mkdirSync(targetDir, { recursive: true });
   for (const skill of SKILLS) {
-    fs.writeFileSync(path.join(targetDir, `${skill.name}.md`), skill.content, "utf8");
+    fs.writeFileSync(path.join(targetDir, `${skill.name}.md`), skill.content, 'utf8');
   }
 }
 
-
 export function buildSkillReferences(workspaceDir: string): string {
-  const dir = path.join(workspaceDir, ".parall", "skills");
-  const lines = SKILLS.map((s) => `- ${s.description.split(":")[0]}: \`${dir}/${s.name}.md\``);
-  return `## Platform Skills (read on demand)\n\n${lines.join("\n")}\n`;
+  const dir = path.join(workspaceDir, '.parall', 'skills');
+  const lines = SKILLS.map((s) => `- ${s.description.split(':')[0]}: \`${dir}/${s.name}.md\``);
+  return `## Platform Skills (read on demand)\n\n${lines.join('\n')}\n`;
 }

package/src/skills/parall-clips.ts

@@ -0,0 +1,44 @@
+export const PARALL_CLIPS_SKILL = `# Parall Clips
+
+Clips are capability extensions — packaged toolkits that give you extra commands (e.g. GitHub operations, web search, code analysis). Clips installed in the org are available for any agent to invoke via the CLI.
+
+## Discovering available clips
+
+\`\`\`bash
+# List all clips installed in the org
+parall clip list
+
+# Show detailed info about a clip (manifest, commands, version)
+parall clip info <alias>
+\`\`\`
+
+## Invoking a clip command
+
+\`\`\`bash
+# Invoke a command on a clip by alias
+parall clip invoke <alias> <command> [input]
+
+# input is optional — when provided, it can be a JSON string or plain text
+parall clip invoke github-tools list-repos '{"org": "acme"}'
+parall clip invoke web-search search "latest Node.js LTS version"
+
+# Custom timeout (default 30s)
+parall clip invoke github-tools create-issue '{"title": "Bug report"}' --timeout 60000
+\`\`\`
+
+## How clips work
+
+1. An org admin installs a clip from the Pinix registry or creates a custom one
+2. \`parall clip list\` shows every clip installed in the org
+3. You can only **invoke** clips that an admin has **bound to you** — invoking an unbound clip returns a "not bound" error. Ask an admin to bind the clip if you need it.
+4. Each clip exposes one or more named commands with typed input/output
+
+## When to use clips
+
+- Check \`parall clip list\` when a task requires capabilities beyond your built-in tools (e.g. GitHub API, external services, specialized analysis)
+- Use \`parall clip info <alias>\` to discover available commands and their expected input format
+- If \`parall clip invoke\` reports the clip isn't bound to you, that clip exists in the org but hasn't been granted to you — ask an admin to bind it
+- Clip invocations return JSON output on success or an error message on failure
+
+CLI command results are JSON on stdout.
+`;

package/src/skills/parall-platform.ts

@@ -115,7 +115,11 @@ parall dm "Alice" --file /tmp/report.pdf --text "Report attached"
 
 ## Approvals
 
-When a CLI command returns a \`PERMISSION_DENIED\` error, the output includes a \`Tip:\` line with an approval-request template — copy it and fill in the remaining placeholders (\`--chat\`, \`--title\`, \`--reason\`). The \`Tip:\` only appears for commonly approvable actions (archive, delete, restore); for other actions, use \`parall approvals actions\` to check if it's approvable.
+When 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):
+- If it IS approvable, a \`Request approval:\` line with a \`parall approvals request\` command follows — fill in the placeholders it shows (\`--chat\`, \`--title\`, \`--reason\`) and run it.
+- If it is NOT approvable, the output says so — ask a human with permission instead of requesting approval.
+
+A 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) — do not request approval for it.
 
 \`\`\`bash
 # Request approval (use action and resource_uri from the error)
@@ -157,5 +161,5 @@ Every entity is addressable with a \`prll://\` URI. Common prefixes you'll see i
 
 When 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).
 
-All CLI output is JSON.
+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/skills/parall-tasks.ts

@@ -61,5 +61,5 @@ When you receive \`[Event: task.comment.created]\`, someone commented on a task
 2. Reply via comment: \`tasks comments add prll://tsk_xxx --body "Response..."\`
 3. If the comment requests status changes, update accordingly
 
-All CLI output is JSON.
+CLI success output is JSON; errors print a JSON line plus, on a \`PERMISSION_DENIED\`, an optional plain-text \`Request approval:\` line — read both.
 `;

package/src/skills/parall-wiki.ts

@@ -127,5 +127,5 @@ parall wiki reset <slug>      # Restore all files to last synced state
 parall wiki log <slug>        # Recent wiki operations
 \`\`\`
 
-All CLI output is JSON. Run \`parall wiki --help\` for full options.
+CLI success output is JSON; errors may add a plain-text \`Request approval:\` line on a \`PERMISSION_DENIED\` — read both. Run \`parall wiki --help\` for full options.
 `;