@parall/agent-core 1.30.0 → 1.32.0

package/dist/provider-config.js

@@ -0,0 +1,41 @@
+export function llmSource(pc) {
+    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) {
+    if (pc?.llm_source)
+        return pc.llm_source;
+    if (pc?.openai_api_key ||
+        pc?.openai_base_url ||
+        pc?.anthropic_auth_token ||
+        pc?.anthropic_base_url) {
+        return 'custom';
+    }
+    return '';
+}
+export function clearAllProviderCreds(env) {
+    delete env.ANTHROPIC_AUTH_TOKEN;
+    delete env.ANTHROPIC_BASE_URL;
+    delete env.ANTHROPIC_API_KEY;
+    delete env.OPENAI_API_KEY;
+    delete env.OPENAI_BASE_URL;
+    delete env.PRLL_CLAUDE_ALLOW_API_KEY;
+}
+export function parseProviderConfig(env) {
+    const raw = env.PRLL_PROVIDER_CONFIG?.trim();
+    if (!raw)
+        return undefined;
+    try {
+        return JSON.parse(raw);
+    }
+    catch (err) {
+        throw new Error(`Invalid PRLL_PROVIDER_CONFIG JSON: ${String(err)}`);
+    }
+}

package/dist/routing.d.ts

@@ -1,14 +1,14 @@
-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: 'main';
 } | {
-    action: "buffer-main";
+    action: 'buffer-main';
 } | {
-    action: "buffer-fork";
+    action: 'buffer-fork';
     forkKey: string;
 } | {
-    action: "new-fork";
+    action: 'new-fork';
 };
 /** Pluggable strategy for routing triggers when main session is busy. */
 export type RoutingStrategy = (event: ParallEvent, state: DispatchState) => TriggerDisposition;

package/dist/routing.js

@@ -8,22 +8,22 @@ const MAX_CONCURRENT_FORKS = 20;
  */
 export const defaultRoutingStrategy = (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 };
+        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. */
 export function routeTrigger(event, state, strategy = defaultRoutingStrategy) {
     const existingForkKey = state.activeForks.get(event.targetId);
     if (existingForkKey)
-        return { action: "buffer-fork", forkKey: existingForkKey };
+        return { action: 'buffer-fork', forkKey: existingForkKey };
     if (!state.mainDispatching)
-        return { action: "main" };
+        return { action: 'main' };
     return strategy(event, state);
 }

package/dist/session-state.d.ts

@@ -14,4 +14,20 @@ export declare function clearDispatchGroupKey(sessionKey: string): void;
 export declare function setDispatchNoReply(sessionKey: string, noReply: boolean): void;
 export declare function getDispatchNoReply(sessionKey: string): boolean;
 export declare function clearDispatchNoReply(sessionKey: string): void;
+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;
+};
+export declare function resetDispatchMetrics(sessionKey: string): void;
+export declare function getDispatchMetrics(sessionKey: string): DispatchMetrics | undefined;
+export declare function clearDispatchMetrics(sessionKey: string): void;
+export declare function recordDeliverText(sessionKey: string, charCount: number): void;
+export declare function recordMessageSend(sessionKey: string, success: boolean): void;
+export declare function recordNoReply(sessionKey: string): void;
+export declare function recordToolCall(sessionKey: string): void;
 //# sourceMappingURL=session-state.d.ts.map

package/dist/session-state.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"session-state.d.ts","sourceRoot":"","sources":["../src/session-state.ts"],"names":[],"mappings":"AAYA,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,QAElE;AAED,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAEvE;AAED,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,QAExE;AAED,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAE1E;AAED,wBAAgB,qBAAqB,CAAC,UAAU,EAAE,MAAM,QAEvD;AAED,2FAA2F;AAC3F,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,QAEzE;AAED,4FAA4F;AAC5F,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAE3E;AAED,wBAAgB,sBAAsB,CAAC,UAAU,EAAE,MAAM,QAExD;AAED,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,QAEvE;AAED,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAE1E;AAED,wBAAgB,qBAAqB,CAAC,UAAU,EAAE,MAAM,QAEvD;AAED,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,QAEtE;AAED,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAE9D;AAED,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,MAAM,QAEtD"}
+{"version":3,"file":"session-state.d.ts","sourceRoot":"","sources":["../src/session-state.ts"],"names":[],"mappings":"AAYA,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,QAElE;AAED,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAEvE;AAED,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,QAExE;AAED,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAE1E;AAED,wBAAgB,qBAAqB,CAAC,UAAU,EAAE,MAAM,QAEvD;AAED,2FAA2F;AAC3F,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,QAEzE;AAED,4FAA4F;AAC5F,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAE3E;AAED,wBAAgB,sBAAsB,CAAC,UAAU,EAAE,MAAM,QAExD;AAED,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,QAEvE;AAED,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAE1E;AAED,wBAAgB,qBAAqB,CAAC,UAAU,EAAE,MAAM,QAEvD;AAED,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,QAEtE;AAED,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAE9D;AAED,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,MAAM,QAEtD;AAMD,MAAM,MAAM,eAAe,GAAG;IAC5B,mBAAmB,EAAE,MAAM,CAAC;IAC5B,kBAAkB,EAAE,MAAM,CAAC;IAC3B,qBAAqB,EAAE,MAAM,CAAC;IAC9B,sBAAsB,EAAE,MAAM,CAAC;IAC/B,eAAe,EAAE,OAAO,CAAC;IACzB,eAAe,EAAE,MAAM,CAAC;IACxB,UAAU,EAAE,MAAM,CAAC;CACpB,CAAC;AAIF,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAU7D;AAED,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS,CAElF;AAED,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAE7D;AAED,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,CAK7E;AAED,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI,CAK5E;AAED,wBAAgB,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAItD;AAED,wBAAgB,cAAc,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAIvD"}

package/dist/session-state.js

@@ -52,3 +52,48 @@ export function getDispatchNoReply(sessionKey) {
 export function clearDispatchNoReply(sessionKey) {
     dispatchNoReplyMap.delete(normalizeSessionKey(sessionKey));
 }
+const dispatchMetricsMap = new Map();
+export function resetDispatchMetrics(sessionKey) {
+    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) {
+    return dispatchMetricsMap.get(normalizeSessionKey(sessionKey));
+}
+export function clearDispatchMetrics(sessionKey) {
+    dispatchMetricsMap.delete(normalizeSessionKey(sessionKey));
+}
+export function recordDeliverText(sessionKey, charCount) {
+    const m = dispatchMetricsMap.get(normalizeSessionKey(sessionKey));
+    if (!m)
+        return;
+    m.deliver_text_chunks++;
+    m.deliver_text_chars += charCount;
+}
+export function recordMessageSend(sessionKey, success) {
+    const m = dispatchMetricsMap.get(normalizeSessionKey(sessionKey));
+    if (!m)
+        return;
+    m.message_send_attempts++;
+    if (success)
+        m.message_send_successes++;
+}
+export function recordNoReply(sessionKey) {
+    const m = dispatchMetricsMap.get(normalizeSessionKey(sessionKey));
+    if (!m)
+        return;
+    m.no_reply_called = true;
+}
+export function recordToolCall(sessionKey) {
+    const m = dispatchMetricsMap.get(normalizeSessionKey(sessionKey));
+    if (!m)
+        return;
+    m.tool_call_count++;
+}

package/dist/skills/index.d.ts

@@ -1,7 +1,8 @@
-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';
 export type SkillMeta = {
     name: string;
     description: string;

package/dist/skills/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/skills/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAC7D,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAC;AAO/D,MAAM,MAAM,SAAS,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAE/E,eAAO,MAAM,MAAM,EAAE,SAAS,EAqB7B,CAAC;AAEF,yEAAyE;AACzE,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAKvD;AAGD,wBAAgB,oBAAoB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAIjE"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/skills/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAC7D,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAC;AAC/D,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAQvD,MAAM,MAAM,SAAS,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAE/E,eAAO,MAAM,MAAM,EAAE,SAAS,EA+B7B,CAAC;AAEF,yEAAyE;AACzE,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAKvD;AAED,wBAAgB,oBAAoB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAIjE"}

package/dist/skills/index.js

@@ -1,44 +1,51 @@
-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";
-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 * 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_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_CLIPS_SKILL } from './parall-clips.js';
 export const SKILLS = [
     {
-        name: "parall-platform",
+        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) {
     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) {
-    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/dist/skills/parall-clips.d.ts

@@ -0,0 +1,2 @@
+export declare const PARALL_CLIPS_SKILL = "# Parall Clips\n\nClips are capability extensions \u2014 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.\n\n## Discovering available clips\n\n```bash\n# List all clips installed in the org\nparall clip list\n\n# Show detailed info about a clip (manifest, commands, version)\nparall clip info <alias>\n```\n\n## Invoking a clip command\n\n```bash\n# Invoke a command on a clip by alias\nparall clip invoke <alias> <command> [input]\n\n# input is optional \u2014 when provided, it can be a JSON string or plain text\nparall clip invoke github-tools list-repos '{\"org\": \"acme\"}'\nparall clip invoke web-search search \"latest Node.js LTS version\"\n\n# Custom timeout (default 30s)\nparall clip invoke github-tools create-issue '{\"title\": \"Bug report\"}' --timeout 60000\n```\n\n## How clips work\n\n1. An org admin installs a clip from the Pinix registry or creates a custom one\n2. `parall clip list` shows every clip installed in the org\n3. You can only **invoke** clips that an admin has **bound to you** \u2014 invoking an unbound clip returns a \"not bound\" error. Ask an admin to bind the clip if you need it.\n4. Each clip exposes one or more named commands with typed input/output\n\n## When to use clips\n\n- Check `parall clip list` when a task requires capabilities beyond your built-in tools (e.g. GitHub API, external services, specialized analysis)\n- Use `parall clip info <alias>` to discover available commands and their expected input format\n- 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 \u2014 ask an admin to bind it\n- Clip invocations return JSON output on success or an error message on failure\n\nCLI command results are JSON on stdout.\n";
+//# sourceMappingURL=parall-clips.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"parall-clips.d.ts","sourceRoot":"","sources":["../../src/skills/parall-clips.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,kBAAkB,y1DA2C9B,CAAC"}

package/dist/skills/parall-clips.js

@@ -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/dist/telemetry.d.ts

@@ -0,0 +1,27 @@
+import { type Span } from '@opentelemetry/api';
+import type { GatewayLogger } from './dispatch-adapter.js';
+import type { DispatchMetrics } from './session-state.js';
+import type { ParallEvent } from './types.js';
+export interface TelemetryHandle {
+    shutdown: () => Promise<void>;
+}
+/**
+ * Initialize agent telemetry. All agents export OTLP to the Parall
+ * telemetry-service (`PRLL_API_URL/otel`), authenticated with `PRLL_API_KEY`.
+ * The service canonicalizes identity from the token and proxies to SigNoz.
+ *
+ * Resource attributes include machine/agent/org identity from env.
+ * Returns a no-op handle when `PRLL_API_URL` is absent (local dev).
+ */
+export declare function initAgentTelemetry(serviceName: string, runtimeType: string): Promise<TelemetryHandle>;
+export declare function startDispatchSpan(event: ParallEvent, runtimeType: string, sessionKey: string): Span | null;
+export declare function endDispatchSpan(span: Span | null, metricsSnapshot: DispatchMetrics | undefined, error?: unknown): void;
+export declare function recordDispatchMetric(event: ParallEvent, runtimeType: string, durationMs: number): void;
+export declare function recordMissingReply(runtimeType: string): void;
+export declare function runWithSessionKey<T>(sessionKey: string, fn: () => T): T;
+/**
+ * Create a GatewayLogger that forwards all levels to OTLP logs.
+ * Two layers: "agent" (runtime) and "daemon".
+ */
+export declare function createOtelLogger(layer: 'agent' | 'daemon', prefix: string): GatewayLogger;
+//# sourceMappingURL=telemetry.d.ts.map

package/dist/telemetry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry.d.ts","sourceRoot":"","sources":["../src/telemetry.ts"],"names":[],"mappings":"AACA,OAAO,EAGL,KAAK,IAAI,EAKV,MAAM,oBAAoB,CAAC;AAE5B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAC3D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAC1D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAkB9C,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/B;AAED;;;;;;;GAOG;AACH,wBAAsB,kBAAkB,CACtC,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,eAAe,CAAC,CAgG1B;AAED,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,WAAW,EAClB,WAAW,EAAE,MAAM,EACnB,UAAU,EAAE,MAAM,GACjB,IAAI,GAAG,IAAI,CAYb;AAED,wBAAgB,eAAe,CAC7B,IAAI,EAAE,IAAI,GAAG,IAAI,EACjB,eAAe,EAAE,eAAe,GAAG,SAAS,EAC5C,KAAK,CAAC,EAAE,OAAO,GACd,IAAI,CAkBN;AAED,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,WAAW,EAClB,WAAW,EAAE,MAAM,EACnB,UAAU,EAAE,MAAM,GACjB,IAAI,CASN;AAED,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAG5D;AAID,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,UAAU,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAEvE;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,QAAQ,EAAE,MAAM,EAAE,MAAM,GAAG,aAAa,CAmCzF"}

package/dist/telemetry.js

@@ -0,0 +1,205 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { trace, metrics, SpanStatusCode, } from '@opentelemetry/api';
+import { SeverityNumber } from '@opentelemetry/api-logs';
+let initialized = false;
+let shutdownFn = null;
+let tracer = null;
+let dispatchCounter = null;
+let dispatchDuration = null;
+let missingReplyCounter = null;
+let otelLogger = null;
+function resolveTargetType(targetId) {
+    if (targetId.startsWith('cht_'))
+        return 'chat';
+    if (targetId.startsWith('tsk_'))
+        return 'task';
+    if (targetId.startsWith('sch_'))
+        return 'schedule';
+    return 'unknown';
+}
+/**
+ * Initialize agent telemetry. All agents export OTLP to the Parall
+ * telemetry-service (`PRLL_API_URL/otel`), authenticated with `PRLL_API_KEY`.
+ * The service canonicalizes identity from the token and proxies to SigNoz.
+ *
+ * Resource attributes include machine/agent/org identity from env.
+ * Returns a no-op handle when `PRLL_API_URL` is absent (local dev).
+ */
+export async function initAgentTelemetry(serviceName, runtimeType) {
+    const noopHandle = { shutdown: async () => { } };
+    const apiUrl = process.env.PRLL_API_URL;
+    const apiKey = process.env.PRLL_API_KEY;
+    if (!apiUrl || !apiKey) {
+        return noopHandle;
+    }
+    try {
+        const otelEndpoint = apiUrl.replace(/\/$/, '') + '/otel';
+        const { OTLPTraceExporter } = await import('@opentelemetry/exporter-trace-otlp-proto');
+        const { OTLPMetricExporter } = await import('@opentelemetry/exporter-metrics-otlp-proto');
+        const { OTLPLogExporter } = await import('@opentelemetry/exporter-logs-otlp-proto');
+        const { NodeTracerProvider, BatchSpanProcessor } = await import('@opentelemetry/sdk-trace-node');
+        const { MeterProvider, PeriodicExportingMetricReader } = await import('@opentelemetry/sdk-metrics');
+        const { LoggerProvider, BatchLogRecordProcessor } = await import('@opentelemetry/sdk-logs');
+        const { Resource } = await import('@opentelemetry/resources');
+        const resource = new Resource({
+            'service.name': serviceName,
+            'service.version': process.env.npm_package_version || 'unknown',
+            'deployment.environment.name': process.env.PRLL_SERVER_ENV || process.env.NODE_ENV || 'development',
+            'parall.runtime_type': runtimeType,
+            'parall.agent_id': process.env.PRLL_AGENT_ID || '',
+            'parall.machine_id': process.env.PRLL_MACHINE_ID || '',
+            'parall.org_id': process.env.PRLL_ORG_ID || '',
+            'parall.daemon_mode': process.env.PRLL_DAEMON_MODE === '1',
+        });
+        const authHeaders = { Authorization: `Bearer ${apiKey}` };
+        const traceExporter = new OTLPTraceExporter({
+            url: `${otelEndpoint}/v1/traces`,
+            headers: authHeaders,
+        });
+        const tracerProvider = new NodeTracerProvider({ resource });
+        tracerProvider.addSpanProcessor(new BatchSpanProcessor(traceExporter));
+        tracerProvider.register();
+        const metricExporter = new OTLPMetricExporter({
+            url: `${otelEndpoint}/v1/metrics`,
+            headers: authHeaders,
+        });
+        const metricReader = new PeriodicExportingMetricReader({
+            exporter: metricExporter,
+            exportIntervalMillis: 15_000,
+        });
+        const meterProvider = new MeterProvider({ resource, readers: [metricReader] });
+        metrics.setGlobalMeterProvider(meterProvider);
+        const logExporter = new OTLPLogExporter({
+            url: `${otelEndpoint}/v1/logs`,
+            headers: authHeaders,
+        });
+        const loggerProvider = new LoggerProvider({ resource });
+        loggerProvider.addLogRecordProcessor(new BatchLogRecordProcessor(logExporter));
+        const meter = metrics.getMeter('parall.agent');
+        tracer = trace.getTracer('parall.agent');
+        otelLogger = loggerProvider.getLogger('parall.agent');
+        dispatchCounter = meter.createCounter('parall.dispatch.count', {
+            description: 'Number of dispatch cycles completed',
+        });
+        dispatchDuration = meter.createHistogram('parall.dispatch.duration', {
+            description: 'Dispatch cycle duration in milliseconds',
+            unit: 'ms',
+        });
+        missingReplyCounter = meter.createCounter('parall.dispatch.missing_reply', {
+            description: 'Dispatches where agent produced text but sent no reply message',
+        });
+        initialized = true;
+        shutdownFn = async () => {
+            await tracerProvider.forceFlush();
+            await meterProvider.forceFlush();
+            await loggerProvider.forceFlush();
+            await tracerProvider.shutdown();
+            await meterProvider.shutdown();
+            await loggerProvider.shutdown();
+        };
+        return {
+            shutdown: async () => {
+                if (shutdownFn)
+                    await shutdownFn();
+            },
+        };
+    }
+    catch {
+        return noopHandle;
+    }
+}
+export function startDispatchSpan(event, runtimeType, sessionKey) {
+    if (!initialized || !tracer)
+        return null;
+    return tracer.startSpan('parall.dispatch', {
+        attributes: {
+            'dispatch.target_type': resolveTargetType(event.targetId),
+            'dispatch.event_type': event.type,
+            'dispatch.runtime_type': runtimeType,
+            'dispatch.session_key': sessionKey,
+            'dispatch.message_id': event.messageId,
+            'dispatch.target_id': event.targetId,
+        },
+    });
+}
+export function endDispatchSpan(span, metricsSnapshot, error) {
+    if (!span)
+        return;
+    if (metricsSnapshot) {
+        span.setAttributes({
+            'dispatch.deliver_text_chunks': metricsSnapshot.deliver_text_chunks,
+            'dispatch.deliver_text_chars': metricsSnapshot.deliver_text_chars,
+            'dispatch.message_send_attempts': metricsSnapshot.message_send_attempts,
+            'dispatch.message_send_successes': metricsSnapshot.message_send_successes,
+            'dispatch.no_reply_called': metricsSnapshot.no_reply_called,
+            'dispatch.tool_call_count': metricsSnapshot.tool_call_count,
+            'dispatch.duration_ms': Date.now() - metricsSnapshot.started_at,
+        });
+    }
+    if (error) {
+        span.setStatus({ code: SpanStatusCode.ERROR, message: String(error) });
+        span.recordException(error instanceof Error ? error : new Error(String(error)));
+    }
+    span.end();
+}
+export function recordDispatchMetric(event, runtimeType, durationMs) {
+    if (!initialized)
+        return;
+    const attrs = {
+        target_type: resolveTargetType(event.targetId),
+        event_type: event.type,
+        runtime_type: runtimeType,
+    };
+    dispatchCounter?.add(1, attrs);
+    dispatchDuration?.record(durationMs, attrs);
+}
+export function recordMissingReply(runtimeType) {
+    if (!initialized)
+        return;
+    missingReplyCounter?.add(1, { runtime_type: runtimeType });
+}
+const sessionKeyStorage = new AsyncLocalStorage();
+export function runWithSessionKey(sessionKey, fn) {
+    return sessionKeyStorage.run(sessionKey, fn);
+}
+/**
+ * Create a GatewayLogger that forwards all levels to OTLP logs.
+ * Two layers: "agent" (runtime) and "daemon".
+ */
+export function createOtelLogger(layer, prefix) {
+    const ts = () => new Date().toISOString();
+    const emit = (severity, msg) => {
+        if (!otelLogger)
+            return;
+        const severityNumber = severity === 'ERROR'
+            ? SeverityNumber.ERROR
+            : severity === 'WARN'
+                ? SeverityNumber.WARN
+                : SeverityNumber.INFO;
+        const attrs = { 'log.layer': layer, 'log.prefix': prefix };
+        const sk = sessionKeyStorage.getStore();
+        if (sk)
+            attrs['session.key'] = sk;
+        otelLogger.emit({
+            severityNumber,
+            severityText: severity,
+            body: msg,
+            attributes: attrs,
+        });
+    };
+    return {
+        info: (msg) => {
+            console.log(`${ts()} [${prefix}] ${msg}`);
+            emit('INFO', msg);
+        },
+        warn: (msg) => {
+            console.warn(`${ts()} [${prefix}] ${msg}`);
+            emit('WARN', msg);
+        },
+        error: (msg) => {
+            console.error(`${ts()} [${prefix}] ${msg}`);
+            emit('ERROR', msg);
+        },
+        child: (sub) => createOtelLogger(layer, `${prefix}:${sub}`),
+    };
+}

package/dist/types.d.ts

@@ -26,10 +26,17 @@ export type DispatchState = {
 };
 /** Normalized inbound event from Parall. */
 export type ParallEvent = {
-    type: "message" | "task" | "task_comment" | "schedule" | "approval";
+    type: 'message' | 'task' | 'task_comment' | 'wiki_comment' | 'schedule' | 'approval';
     targetId: string;
     targetName?: string;
     targetType?: string;
+    /**
+     * Full `prll://` target URI to reply on, used for wiki_comment events where
+     * the reply goes back to the same wiki page / changeset via
+     * `parall comments add --target <uri>`. Carried separately from `targetId`
+     * (a bare entity id) because the reply needs the full URI incl. path/anchor.
+     */
+    replyTargetUri?: string;
     deliveryReason?: string;
     senderId: string;
     senderName: string;
@@ -50,7 +57,16 @@ export type ParallEvent = {
     /** 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";
+    ackSourceType?: 'message' | 'task_activity' | 'comment' | 'schedule_run';
     ackSourceId?: string;
+    /** Unread message count in the target chat since agent's last interaction. */
+    unreadCount?: number;
+    /** Channel cursor: the last message ID the agent read. */
+    unreadSince?: string;
+    /** For thread replies: total replies and unread replies in the thread. */
+    threadReplyCount?: number;
+    threadUnreadCount?: number;
+    /** Thread cursor: the last reply ID the agent read in this thread. */
+    threadUnreadSince?: string;
 };
 //# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,2FAA2F;AAC3F,MAAM,MAAM,UAAU,GAAG;IACvB,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IACjE,mFAAmF;IACnF,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,sFAAsF;IACtF,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,qFAAqF;IACrF,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF,2DAA2D;AAC3D,MAAM,MAAM,aAAa,GAAG;IAC1B,eAAe,EAAE,OAAO,CAAC;IACzB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,kBAAkB,EAAE,UAAU,EAAE,CAAC;IACjC,UAAU,EAAE,WAAW,EAAE,CAAC;IAC1B,oFAAoF;IACpF,0BAA0B,CAAC,EAAE,MAAM,CAAC;CACrC,CAAC;AAEF,4CAA4C;AAC5C,MAAM,MAAM,WAAW,GAAG;IACxB,IAAI,EAAE,SAAS,GAAG,MAAM,GAAG,cAAc,GAAG,UAAU,GAAG,UAAU,CAAC;IACpE,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,WAAW,CAAC,EAAE,KAAK,CAAC;QAClB,EAAE,EAAE,MAAM,CAAC;QACX,QAAQ,EAAE,MAAM,CAAC;QACjB,QAAQ,EAAE,MAAM,CAAC;QACjB,QAAQ,EAAE,MAAM,CAAC;KAClB,CAAC,CAAC;IACH,8DAA8D;IAC9D,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,oEAAoE;IACpE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;8EAC0E;IAC1E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,aAAa,CAAC,EAAE,SAAS,GAAG,eAAe,GAAG,SAAS,GAAG,cAAc,CAAC;IACzE,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,2FAA2F;AAC3F,MAAM,MAAM,UAAU,GAAG;IACvB,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IACjE,mFAAmF;IACnF,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,sFAAsF;IACtF,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,qFAAqF;IACrF,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF,2DAA2D;AAC3D,MAAM,MAAM,aAAa,GAAG;IAC1B,eAAe,EAAE,OAAO,CAAC;IACzB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,kBAAkB,EAAE,UAAU,EAAE,CAAC;IACjC,UAAU,EAAE,WAAW,EAAE,CAAC;IAC1B,oFAAoF;IACpF,0BAA0B,CAAC,EAAE,MAAM,CAAC;CACrC,CAAC;AAEF,4CAA4C;AAC5C,MAAM,MAAM,WAAW,GAAG;IACxB,IAAI,EAAE,SAAS,GAAG,MAAM,GAAG,cAAc,GAAG,cAAc,GAAG,UAAU,GAAG,UAAU,CAAC;IACrF,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;;OAKG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,WAAW,CAAC,EAAE,KAAK,CAAC;QAClB,EAAE,EAAE,MAAM,CAAC;QACX,QAAQ,EAAE,MAAM,CAAC;QACjB,QAAQ,EAAE,MAAM,CAAC;QACjB,QAAQ,EAAE,MAAM,CAAC;KAClB,CAAC,CAAC;IACH,8DAA8D;IAC9D,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,oEAAoE;IACpE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;8EAC0E;IAC1E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,aAAa,CAAC,EAAE,SAAS,GAAG,eAAe,GAAG,SAAS,GAAG,cAAc,CAAC;IACzE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,8EAA8E;IAC9E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,0DAA0D;IAC1D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,0EAA0E;IAC1E,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,sEAAsE;IACtE,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@parall/agent-core",
-  "version": "1.30.0",
+  "version": "1.32.0",
   "description": "Shared agent runtime orchestration helpers for Parall",
   "license": "MIT",
   "repository": {
@@ -26,7 +26,16 @@
     "src"
   ],
   "dependencies": {
-    "@parall/sdk": "1.30.0"
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/api-logs": "^0.57.0",
+    "@opentelemetry/exporter-logs-otlp-proto": "^0.57.0",
+    "@opentelemetry/exporter-metrics-otlp-proto": "^0.57.0",
+    "@opentelemetry/exporter-trace-otlp-proto": "^0.57.0",
+    "@opentelemetry/resources": "^1.30.0",
+    "@opentelemetry/sdk-logs": "^0.57.0",
+    "@opentelemetry/sdk-metrics": "^1.30.0",
+    "@opentelemetry/sdk-trace-node": "^1.30.0",
+    "@parall/sdk": "1.32.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",