@parall/agent-core 1.23.0 → 1.25.0

package/src/prompt-fragments.ts

@@ -30,13 +30,20 @@ function sanitizeProfileField(value: string): string {
   return value.replace(/[\r\n]+/g, " ").replace(/`/g, "'").trim();
 }
 
+function sanitizeProfileBlock(value: string): string {
+  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", ""];
   lines.push(`You are **${name}** (\`prll://${agent.userId}\`).`);
   if (agent.description) {
-    lines.push(`Description: ${sanitizeProfileField(agent.description)}`);
+    const description = sanitizeProfileBlock(agent.description);
+    if (description) {
+      lines.push("", "### Your Agent Profile", "", description);
+    }
   }
   lines.push(
     "",
@@ -80,6 +87,14 @@ acting, unless you've been explicitly authorized.
 Other agents share this workspace. Before starting work, check whether someone
 — human or agent — has already picked it up. Coordination beats racing.
 
+### 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.
+
 ### When in doubt
 Prefer asking over guessing. Prefer "I don't know" over fabricating. Your
 credibility is what you bring to the workspace — protect it.`;
@@ -133,9 +148,9 @@ resolves and renders the entity title automatically.
 An event only carries the single triggering message. If you're mentioned in a
 group chat and lack context, pull what you need from the chat — don't guess:
 
-    npx --yes @parall/cli@latest messages list cht_xxx --limit 20 --before msg_xxx
-    npx --yes @parall/cli@latest messages get msg_xxx
-    npx --yes @parall/cli@latest chats get cht_xxx
+    parall messages list cht_xxx --limit 20 --before msg_xxx
+    parall messages get msg_xxx
+    parall chats get cht_xxx
 
 Rule of thumb: in a group chat mention, the conversation that led up to you
 being called almost always matters — read it before replying. In a DM, your
@@ -152,17 +167,17 @@ Messages may include attachments. They appear in events as:
 
 To download an attachment, use the CLI:
 
-    npx @parall/cli@latest files download att_xxx --output /tmp/screenshot.png
+    parall files download att_xxx --output /tmp/screenshot.png
 
 To send a file:
 
-    npx @parall/cli@latest messages send prll://cht_xxx --file /tmp/output.png --text "Done"
+    parall messages send prll://cht_xxx --file /tmp/output.png --text "Done"
 
 Or upload first and reuse across chats:
 
-    npx @parall/cli@latest files upload /tmp/report.pdf
-    npx @parall/cli@latest messages send prll://cht_aaa --attachment att_yyy --text "Report"
-    npx @parall/cli@latest messages send prll://cht_bbb --attachment att_yyy --text "FYI"
+    parall files upload /tmp/report.pdf
+    parall messages send prll://cht_aaa --attachment att_yyy --text "Report"
+    parall messages send prll://cht_bbb --attachment att_yyy --text "FYI"
 
 ### When to reference
 
@@ -176,3 +191,47 @@ Or upload first and reuse across chats:
 
 Other agents and humans read your output. References build a navigable context graph —
 in multi-agent workflows, your references are the map that the next agent follows.`;
+
+export type PreparedLocalImage = {
+  attachmentId: string;
+  fileName: string;
+  mimeType: string;
+  fileSize: number;
+  localPath: string;
+};
+
+export type LocalAttachmentResult = {
+  images: PreparedLocalImage[];
+  notes: string[];
+};
+
+export function renderLocalAttachmentSection(section: LocalAttachmentResult): string {
+  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-
+  // reading tools can consume it verbatim — paths inside the attachment root
+  // are sanitized to ASCII-safe segments, and the workspace dir comes from
+  // 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]"];
+  for (const image of section.images) {
+    lines.push(
+      `- prll://${image.attachmentId} (${sanitizePromptMeta(image.mimeType)}, ${formatBytes(image.fileSize)}, ${sanitizePromptMeta(image.fileName)})`,
+      `  ${image.localPath}`,
+    );
+  }
+  lines.push(...section.notes);
+  return lines.join("\n");
+}
+
+function sanitizePromptMeta(value: string): string {
+  return value.replace(/[\r\n]+/g, " ").replace(/[()]/g, " ").trim();
+}
+
+export function formatBytes(bytes: number): string {
+  if (bytes >= 1048576) return `${(bytes / 1048576).toFixed(1)}MB`;
+  if (bytes >= 1024) return `${Math.round(bytes / 1024)}KB`;
+  return `${bytes}B`;
+}

package/src/types.ts

@@ -20,6 +20,7 @@ export type ParallEvent = {
   targetId: string;
   targetName?: string;
   targetType?: string;
+  deliveryReason?: string;
   senderId: string;
   senderName: string;
   messageId: string;