@borgee/agents-host 0.2.97 → 0.2.101

package/dist/types.d.ts

@@ -1,3 +1,4 @@
+import type { ExecutionGrant } from './plugin-sdk.js';
 export type ProviderKind = 'claude' | 'codex' | 'copilot';
 export type ProjectionStrategy = 'session-brief' | 'turn-full' | 'message-only' | 'turn-thin' | 'file-brief';
 export interface ProviderCommandConfig {
@@ -111,6 +112,8 @@ export interface ChannelMessageEvent {
     content_type?: string;
     attachments?: HostedMessageAttachment[];
     created_at?: number;
+    /** Server-issued capability used only by the execution telemetry rail. */
+    execution_grant?: ExecutionGrant;
     [key: string]: unknown;
 }
 export interface MeResponseUser {
@@ -135,6 +138,36 @@ export interface ChannelHistoryEntry {
     createdAt: number;
     editedAt?: number;
 }
+export interface ChannelFileEntry {
+    id: string;
+    ownerUserId: string;
+    channelId: string;
+    path: string;
+    parentPath: string;
+    name: string;
+    isDirectory: boolean;
+    mimeType: string;
+    sizeBytes: number;
+    source: string;
+    sourceMessageId: string;
+    createdAt: number;
+    updatedAt: number;
+}
+export interface ChannelFileContent {
+    path: string;
+    filename: string;
+    contentType: string;
+    sizeBytes: number;
+    base64?: string;
+    text?: string;
+}
+export interface PublishChannelFileInput {
+    channelId: string;
+    path: string;
+    contentType: string;
+    base64: string;
+    overwrite: boolean;
+}
 export interface HostedMessageAttachment {
     url: string;
     filename?: string;
@@ -454,6 +487,12 @@ export interface ProviderReply {
      */
     sessionId?: string;
 }
+export interface ProviderTokenUsage {
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens: number;
+    cacheWriteTokens: number;
+}
 export interface PostedMessage {
     messageId: string;
 }
@@ -588,4 +627,6 @@ export type ProviderProgressUpdate = {
 };
 export interface ProviderGenerateOptions {
     onProgress?: (update: ProviderProgressUpdate) => void;
+    onUsage?: (usage: ProviderTokenUsage) => void;
+    onExecutionContinuation?: (completion: Promise<boolean>) => void;
 }

package/dist/typing-lease.d.ts

@@ -0,0 +1,14 @@
+export interface TypingLease {
+    renew(): void;
+    stop(): void;
+}
+/**
+ * Keeps typing truthful without making provider completion its only release.
+ *
+ * A lease reports one pulse immediately. Visible answer updates may renew it
+ * at most once per interval; nothing is scheduled between updates. Browser
+ * expiry bounds every pulse, so a provider turn can keep running tools or
+ * background work while the activity rail says "working" without a hidden
+ * periodic heartbeat surviving indefinitely.
+ */
+export declare function startTypingLease(reportTyping: () => void, now?: () => number): TypingLease;

package/dist/typing-lease.js

@@ -0,0 +1,31 @@
+const TYPING_PULSE_INTERVAL_MS = 2_000;
+/**
+ * Keeps typing truthful without making provider completion its only release.
+ *
+ * A lease reports one pulse immediately. Visible answer updates may renew it
+ * at most once per interval; nothing is scheduled between updates. Browser
+ * expiry bounds every pulse, so a provider turn can keep running tools or
+ * background work while the activity rail says "working" without a hidden
+ * periodic heartbeat surviving indefinitely.
+ */
+export function startTypingLease(reportTyping, now = () => performance.now()) {
+    let closed = false;
+    let lastPulseAt = now();
+    reportTyping();
+    return {
+        renew: () => {
+            if (closed) {
+                return;
+            }
+            const currentTime = now();
+            if (currentTime - lastPulseAt < TYPING_PULSE_INTERVAL_MS) {
+                return;
+            }
+            lastPulseAt = currentTime;
+            reportTyping();
+        },
+        stop: () => {
+            closed = true;
+        },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@borgee/agents-host",
-  "version": "0.2.97",
+  "version": "0.2.101",
   "private": false,
   "publishConfig": {
     "access": "public"
@@ -38,7 +38,7 @@
     "tsx": "^4.20.5",
     "typescript": "^5.9.3",
     "vitest": "^4.1.5",
-    "@borgee/plugin-sdk": "0.15.0"
+    "@borgee/plugin-sdk": "0.15.3"
   },
   "scripts": {
     "predev": "pnpm --filter @borgee/agent-remote-protocol build && pnpm --filter @borgee/plugin-sdk build && pnpm run vendor:claude",

package/skills/borgee-agent/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: borgee-agent
-description: Read the Borgee channel this turn is running in and act on its tasks — channel history, visible participants, task list/create/get/update, task properties, and short auxiliary mentions — through the packaged local CLI. Use when you need to know what was said in this channel, who is here, or what the current task is, and when you need to record task state or ping another participant.
+description: Read the Borgee channel this turn is running in and act on its tasks — channel history, channel files, visible participants, task list/create/get/update, task properties, and short auxiliary mentions — through the packaged local CLI. Use when you need to know what was said in this channel, which files it already holds, who is here, or what the current task is, and when you need to record task state or ping another participant.
 ---
 
 # Borgee channel agent
 
-This turn is running as an agent inside a Borgee channel. The packaged CLI is the only way to see that channel and to act on its tasks: it talks to a loopback-only gateway that is already authorized for this channel and this turn. This file is the whole manual — the invocation, every command, what is reachable when, and the limits.
+This turn is running as an agent inside a Borgee channel. The packaged CLI is the only way to see that channel, list its files, and act on its tasks: it talks to a loopback-only gateway that is already authorized for this channel and this turn. This file is the whole manual — the invocation, every command, what is reachable when, and the limits.
 
 ## Authorization
 
@@ -52,6 +52,11 @@ Everything below writes that leading interpreter and script path as `borgee-agen
 | `bootstrap` | The channel context the host published for this turn: the channel id, whether collaboration is live, and inside a task thread the current task id. The one command whose answer you cannot predict. |
 | `whoami` | This agent's own id and display name. |
 | `history [--limit <n>] [--before <n>] [--after <n>]` | Recent messages in this channel. At most 20 per call — a larger `--limit` is silently reduced to 20, so page with `--before` rather than asking for more. `--before` and `--after` are `createdAt` epoch-millisecond cursors copied from a message you already hold, not message ids and not counts. |
+| `files` | Files visible in this channel, returned as a flattened list with stable root-relative paths and basic metadata. |
+| `files cat <channel-path>` | Print one UTF-8 text file. The file must have a supported text MIME type and be at most 64 KiB. |
+| `files download <channel-path> [--overwrite]` | Copy one channel file to `<execution.local_directory>/.borgee/channel-files/<channel-path>`. The default refuses an existing working copy. |
+| `files sync [<channel-path>] [--overwrite]` | Copy every visible file, or one exact path/subtree, into the same fixed working-copy directory. File bytes never appear in command output. |
+| `files publish <local-relative-path> --channel-path <channel-path> [--content-type <mime>] [--overwrite]` | Explicitly publish one regular file under `execution.local_directory`. The default is create-only; `--overwrite` is required to replace an existing channel file. |
 | `users` | Every participant you share a channel, DM or thread with. That is a superset of this channel's members, not its roster. |
 | `draft --turn-execution-id <id>` | This turn's host-private in-flight draft. It exists only once this turn has produced visible reply text, and answers `not_found` before that. |
 | `send --body <text> --turn-execution-id <id> (--reply-to <message-id> \| --mention <user-id>)...` | Post a short auxiliary message. It must address someone. |
@@ -70,7 +75,7 @@ The keys `task set-property` and `task delete-property` accept are a closed set,
 
 ## What is available on a turn
 
-`health`, `bootstrap`, `whoami`, `history`, `users` and the task commands are live on every turn whose prompt names a gateway credential file.
+`health`, `bootstrap`, `whoami`, `history`, `files`, `users` and the task commands are live on every turn whose prompt names a gateway credential file. File listing and `files cat` work without a task execution directory. Download, sync and publish require a task execution target with an absolute `execution.local_directory`.
 
 `draft`, `send` and `mention` are live only where collaboration is enabled; the prompt says when they are not, and the gateway answers `not_found` for all three. They additionally need the turn execution id the prompt carries: no command returns that id and the gateway credential file does not hold it.
 
@@ -137,7 +142,10 @@ $ borgee-agent --gateway /state/channels/channel-a/.borgee-agent-gateway.json \
 ## Constraints
 
 - Local only. The CLI reaches the loopback gateway and nothing else.
-- It does not read or write files anywhere except the one gateway credential file it is handed.
+- File transfer accepts only portable relative paths. Absolute paths, `..`, backslashes, symbolic-link traversal, non-regular publish sources and files larger than 10 MiB are rejected.
+- Download and sync write only below `<execution.local_directory>/.borgee/channel-files`; publish reads only below `execution.local_directory`.
+- Channel files are shared inputs and the fixed local directory is a working copy. Local changes are not shared until an explicit `files publish`.
+- Published files are classified as explicit Agent publishes. Publish is create-only unless `--overwrite` is explicit; it cannot write arbitrary shared storage.
 - Auxiliary sends are short notices — one line, at most twelve words counting the `<@id>` the CLI appends, addressed to someone or attached to a message. They are not a place for the answer.
 - Exactly one auxiliary send per turn, whoever it addresses. A send the gateway rejects does not spend it.
 - The draft is host-private. Read it to see what the host is about to post; never re-post it.

package/skills/borgee-agent/scripts/borgee-agent.mjs

@@ -18,6 +18,16 @@ Commands:
       This agent's identity in this channel.
   history [--limit <n>] [--before <n>] [--after <n>]
       Recent messages in this channel.
+  files
+      Files visible in this channel.
+  files cat <channel-path>
+      Print one UTF-8 text file up to 64 KiB.
+  files download <channel-path> [--overwrite]
+      Copy one file into execution.local_directory/.borgee/channel-files.
+  files sync [<channel-path>] [--overwrite]
+      Copy all files, or one subtree, into the fixed working-copy directory.
+  files publish <local-relative-path> --channel-path <channel-path> [--content-type <mime>] [--overwrite]
+      Explicitly publish one execution.local_directory file. Existing channel files are preserved unless --overwrite is present.
   users
       Participants visible in this channel.
   draft --turn-execution-id <id>
@@ -75,6 +85,7 @@ const COMMANDS = new Set([
   'bootstrap',
   'whoami',
   'history',
+  'files',
   'users',
   'draft',
   'send',
@@ -91,6 +102,7 @@ const TASK_COMMANDS = new Set([
   'set-property',
   'delete-property',
 ]);
+const FILE_COMMANDS = new Set(['cat', 'download', 'sync', 'publish']);
 
 class UsageError extends Error {}
 
@@ -114,6 +126,9 @@ function parseArgs(argv) {
   let status;
   let propertyKey;
   let propertyValue;
+  let channelPath;
+  let contentType;
+  let overwrite = false;
   let index = 0;
 
   const takeValue = (flag) => {
@@ -193,6 +208,15 @@ function parseArgs(argv) {
       case '--value':
         propertyValue = takeValue(arg);
         break;
+      case '--channel-path':
+        channelPath = trimArgument(takeValue(arg));
+        break;
+      case '--content-type':
+        contentType = trimArgument(takeValue(arg));
+        break;
+      case '--overwrite':
+        overwrite = true;
+        break;
       default:
         throw new UsageError(`Unknown argument: ${arg}`);
     }
@@ -209,6 +233,8 @@ function parseArgs(argv) {
   let taskCommand = null;
   let taskId = null;
   let mentionTargetId = null;
+  let fileCommand = null;
+  let filePath = null;
   let consumed = 1;
   if (command === 'task') {
     if (positionals.length < 2) {
@@ -232,6 +258,16 @@ function parseArgs(argv) {
       }
       consumed += 1;
     }
+  } else if (command === 'files' && positionals.length > consumed) {
+    fileCommand = positionals[consumed];
+    if (!FILE_COMMANDS.has(fileCommand)) {
+      throw new UsageError(`Unknown files command: ${fileCommand}`);
+    }
+    consumed += 1;
+    if (positionals.length > consumed) {
+      filePath = trimArgument(positionals[consumed]);
+      consumed += 1;
+    }
   } else if (command === 'mention' && positionals.length > consumed) {
     mentionTargetId = trimArgument(positionals[consumed]);
     consumed += 1;
@@ -267,6 +303,11 @@ function parseArgs(argv) {
     status,
     propertyKey,
     propertyValue,
+    fileCommand,
+    filePath,
+    channelPath,
+    contentType,
+    overwrite,
   };
 }
 
@@ -303,6 +344,14 @@ function validateCommand(parsed) {
     return;
   }
   if (parsed.command !== 'task') {
+    if (parsed.command === 'files' && parsed.fileCommand !== null) {
+      if (parsed.fileCommand !== 'sync' || parsed.filePath !== null) {
+        requireText(parsed.filePath, parsed.fileCommand === 'publish' ? 'local path' : 'channel path', label);
+      }
+      if (parsed.fileCommand === 'publish') {
+        requireText(parsed.channelPath, '--channel-path', label);
+      }
+    }
     return;
   }
   if (parsed.taskCommand === 'create') {
@@ -486,6 +535,39 @@ function resolveRequest(credential, parsed) {
       body: null,
     };
   }
+  if (parsed.command === 'files' && parsed.fileCommand === null) {
+    return { url: `${baseUrl}/v1/channels/${channel}/files`, method: 'GET', body: null };
+  }
+  if (parsed.command === 'files' && parsed.fileCommand === 'cat') {
+    const query = buildQuery([['path', parsed.filePath]]);
+    return { url: `${baseUrl}/v1/channels/${channel}/files/content${query}`, method: 'GET', body: null };
+  }
+  if (parsed.command === 'files' && parsed.fileCommand === 'download') {
+    return {
+      url: `${baseUrl}/v1/channels/${channel}/files/download`,
+      method: 'POST',
+      body: { path: parsed.filePath, overwrite: parsed.overwrite },
+    };
+  }
+  if (parsed.command === 'files' && parsed.fileCommand === 'sync') {
+    return {
+      url: `${baseUrl}/v1/channels/${channel}/files/sync`,
+      method: 'POST',
+      body: { ...(parsed.filePath !== null ? { path: parsed.filePath } : {}), overwrite: parsed.overwrite },
+    };
+  }
+  if (parsed.command === 'files' && parsed.fileCommand === 'publish') {
+    return {
+      url: `${baseUrl}/v1/channels/${channel}/files/publish`,
+      method: 'POST',
+      body: {
+        sourcePath: parsed.filePath,
+        channelPath: parsed.channelPath,
+        ...(parsed.contentType ? { contentType: parsed.contentType } : {}),
+        overwrite: parsed.overwrite,
+      },
+    };
+  }
   if (parsed.command === 'users') {
     return { url: `${baseUrl}/v1/channels/${channel}/users`, method: 'GET', body: null };
   }
@@ -541,6 +623,13 @@ async function main() {
   validateCommand(parsed);
   const credential = await readGatewayCredential(parsed.gatewayCredentialPath);
   const result = await callGateway(credential, resolveRequest(credential, parsed));
+  if (parsed.command === 'files' && parsed.fileCommand === 'cat') {
+    process.stdout.write(result.text);
+    if (!result.text.endsWith('\n')) {
+      process.stdout.write('\n');
+    }
+    return 0;
+  }
   process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
   return 0;
 }

package/skills/borgee-agent/scripts/borgee-agent.py

@@ -25,6 +25,16 @@ Commands:
       This agent's identity in this channel.
   history [--limit <n>] [--before <n>] [--after <n>]
       Recent messages in this channel.
+  files
+      Files visible in this channel.
+  files cat <channel-path>
+      Print one UTF-8 text file up to 64 KiB.
+  files download <channel-path> [--overwrite]
+      Copy one file into execution.local_directory/.borgee/channel-files.
+  files sync [<channel-path>] [--overwrite]
+      Copy all files, or one subtree, into the fixed working-copy directory.
+  files publish <local-relative-path> --channel-path <channel-path> [--content-type <mime>] [--overwrite]
+      Explicitly publish one execution.local_directory file. Existing channel files are preserved unless --overwrite is present.
   users
       Participants visible in this channel.
   draft --turn-execution-id <id>
@@ -72,6 +82,7 @@ COMMANDS = frozenset(
         "bootstrap",
         "whoami",
         "history",
+        "files",
         "users",
         "draft",
         "send",
@@ -91,6 +102,7 @@ TASK_COMMANDS = frozenset(
         "delete-property",
     }
 )
+FILE_COMMANDS = frozenset({"cat", "download", "sync", "publish"})
 
 
 class UsageError(Exception):
@@ -121,6 +133,9 @@ def parse_args(argv: list[str]) -> dict[str, object]:
     status: str | None = None
     property_key: str | None = None
     property_value: str | None = None
+    channel_path: str | None = None
+    content_type: str | None = None
+    overwrite = False
     index = 0
 
     def take_value(flag: str) -> str:
@@ -176,6 +191,12 @@ def parse_args(argv: list[str]) -> dict[str, object]:
             property_key = trim_argument(take_value(arg))
         elif arg == "--value":
             property_value = take_value(arg)
+        elif arg == "--channel-path":
+            channel_path = trim_argument(take_value(arg))
+        elif arg == "--content-type":
+            content_type = trim_argument(take_value(arg))
+        elif arg == "--overwrite":
+            overwrite = True
         else:
             raise UsageError(f"Unknown argument: {arg}")
         index += 1
@@ -189,6 +210,8 @@ def parse_args(argv: list[str]) -> dict[str, object]:
     task_command: str | None = None
     task_id: str | None = None
     mention_target_id: str | None = None
+    file_command: str | None = None
+    file_path: str | None = None
     consumed = 1
     if command == "task":
         if len(positionals) < 2:
@@ -209,6 +232,14 @@ def parse_args(argv: list[str]) -> dict[str, object]:
                     f'Empty task id for "task {task_command}"; pass a task id or omit the argument entirely'
                 )
             consumed += 1
+    elif command == "files" and len(positionals) > consumed:
+        file_command = positionals[consumed]
+        if file_command not in FILE_COMMANDS:
+            raise UsageError(f"Unknown files command: {file_command}")
+        consumed += 1
+        if len(positionals) > consumed:
+            file_path = trim_argument(positionals[consumed])
+            consumed += 1
     elif command == "mention" and len(positionals) > consumed:
         mention_target_id = trim_argument(positionals[consumed])
         consumed += 1
@@ -240,6 +271,11 @@ def parse_args(argv: list[str]) -> dict[str, object]:
         "status": status,
         "property_key": property_key,
         "property_value": property_value,
+        "file_command": file_command,
+        "file_path": file_path,
+        "channel_path": channel_path,
+        "content_type": content_type,
+        "overwrite": overwrite,
     }
 
 
@@ -272,6 +308,16 @@ def validate_command(parsed: dict[str, object]) -> None:
         require_text(parsed["body"], "--body", label)
         require_text(parsed["turn_execution_id"], "--turn-execution-id", label)
         return
+    if command == "files" and parsed["file_command"] is not None:
+        if parsed["file_command"] != "sync" or parsed["file_path"] is not None:
+            require_text(
+                parsed["file_path"],
+                "local path" if parsed["file_command"] == "publish" else "channel path",
+                label,
+            )
+        if parsed["file_command"] == "publish":
+            require_text(parsed["channel_path"], "--channel-path", label)
+        return
     if command != "task":
         return
     task_command = parsed["task_command"]
@@ -464,6 +510,44 @@ def resolve_request(credential: dict[str, str], parsed: dict[str, object]) -> di
             "method": "GET",
             "body": None,
         }
+    if command == "files":
+        file_command = parsed["file_command"]
+        if file_command == "cat":
+            query = build_query([("path", parsed["file_path"])])
+            return {
+                "url": f"{base_url}/v1/channels/{channel}/files/content{query}",
+                "method": "GET",
+                "body": None,
+            }
+        if file_command == "download":
+            return {
+                "url": f"{base_url}/v1/channels/{channel}/files/download",
+                "method": "POST",
+                "body": {"path": parsed["file_path"], "overwrite": parsed["overwrite"]},
+            }
+        if file_command == "sync":
+            body = {"overwrite": parsed["overwrite"]}
+            if parsed["file_path"] is not None:
+                body["path"] = parsed["file_path"]
+            return {
+                "url": f"{base_url}/v1/channels/{channel}/files/sync",
+                "method": "POST",
+                "body": body,
+            }
+        if file_command == "publish":
+            body = {
+                "sourcePath": parsed["file_path"],
+                "channelPath": parsed["channel_path"],
+                "overwrite": parsed["overwrite"],
+            }
+            if parsed["content_type"] is not None:
+                body["contentType"] = parsed["content_type"]
+            return {
+                "url": f"{base_url}/v1/channels/{channel}/files/publish",
+                "method": "POST",
+                "body": body,
+            }
+        return {"url": f"{base_url}/v1/channels/{channel}/files", "method": "GET", "body": None}
     if command == "users":
         return {"url": f"{base_url}/v1/channels/{channel}/users", "method": "GET", "body": None}
     if command == "draft":
@@ -532,6 +616,12 @@ def main() -> int:
     validate_command(parsed)
     credential = read_gateway_credential(str(parsed["gateway_credential_path"]))
     result = call_gateway(credential, resolve_request(credential, parsed))
+    if parsed["command"] == "files" and parsed["file_command"] == "cat":
+        text = str(result["text"])
+        if not text.endswith("\n"):
+            text += "\n"
+        sys.stdout.buffer.write(text.encode("utf-8"))
+        return 0
     sys.stdout.write(json.dumps(result, indent=2, ensure_ascii=False) + "\n")
     return 0