@borgee/agents-host 0.2.33 → 0.2.35

package/dist/providers/create-provider.js

@@ -2,6 +2,7 @@ import { FileChannelContextStore } from '../context/injection.js';
 import { createProviderConnectionsSessionStore } from '../connections-state-store.js';
 import { ProviderTurnPreparer } from '../context/turn-preparation.js';
 import { CONNECTIONS_STATE_LAYER_COMPATIBILITY_GATE, CONTEXT_INJECTION_COMPATIBILITY_GATE, CODEX_PROVIDER_COMPATIBILITY_GATE, COPILOT_PROVIDER_V2_COMPATIBILITY_GATE, INTERNAL_PROVIDER_IMPLEMENTATIONS_ENV, LOCALHOST_GATEWAY_COMPATIBILITY_GATE, parseInternalProviderImplementationOverrides, POLICY_AUDIT_ENFORCEMENT_COMPATIBILITY_GATE, resolveInternalPolicyMode, resolveInternalCompatibilityGates, SKILL_RUNTIME_COMPATIBILITY_GATE, } from '../compatibility-gates.js';
+import { resolveIdleBackendShutdownMs } from './idle-backend-shutdown.js';
 import { ClaudeCliClient } from './claude/cli-client.js';
 import { ClaudeProviderAdapter } from './claude/adapter.js';
 import { FileClaudeChannelSessionStore } from './claude/session-store.js';
@@ -39,7 +40,9 @@ class CliBackedProviderV2 {
         const text = await this.cli.generateReply(input.turn, {
             onProgress: createAwaitingUserProgressHandler(options?.onProgress),
         });
-        return parseProviderReply(text);
+        // Read the session AFTER the turn: a first turn on a channel opens the
+        // session as it runs, so before this point there is nothing to report.
+        return { ...parseProviderReply(text), sessionId: this.cli.sessionIdForChannel(input.turn.channelId) };
     }
     async shutdown() {
         await this.cli.dispose();
@@ -57,8 +60,8 @@ function resolveCopilotImplementation(routingConfig) {
     }
     return routingConfig.implementationOverrides.copilot ?? 'v2';
 }
-function createClaudeProvider(config, debugLogger, connectionsStateGateEnabled, turnPreparer) {
-    const cli = new ClaudeCliClient(config.claudeCommand, config.claudeArgs, {}, createProviderConnectionsSessionStore({
+function createClaudeProvider(config, debugLogger, connectionsStateGateEnabled, turnPreparer, idleBackendShutdownMs) {
+    const cli = new ClaudeCliClient(config.claudeCommand, config.claudeArgs, { idleBackendShutdownMs }, createProviderConnectionsSessionStore({
         provider: 'claude',
         legacyStore: new FileClaudeChannelSessionStore({
             resolvePath: (agentId) => resolveClaudeSessionMapPath(config.stateRootDir, agentId),
@@ -69,10 +72,11 @@ function createClaudeProvider(config, debugLogger, connectionsStateGateEnabled,
     }), config.resolveStableAgentId, debugLogger);
     return new ClaudeProviderAdapter(cli, turnPreparer);
 }
-function createCopilotProvider(config, debugLogger, connectionsStateGateEnabled, implementation, turnPreparer, policyAuditGateEnabled, authorizationAuditSink) {
+function createCopilotProvider(config, debugLogger, connectionsStateGateEnabled, implementation, turnPreparer, policyAuditGateEnabled, authorizationAuditSink, idleBackendShutdownMs) {
     const policyMode = resolveInternalPolicyMode(policyAuditGateEnabled);
     const cli = new CopilotCliClient(config.copilotCommand, config.copilotArgs, {
         idleSessionTtlMs: config.copilotSessionTtlMinutes * 60 * 1000,
+        idleBackendShutdownMs,
     }, createProviderConnectionsSessionStore({
         provider: 'copilot',
         legacyStore: new FileCopilotChannelSessionStore({
@@ -90,8 +94,8 @@ function createCopilotProvider(config, debugLogger, connectionsStateGateEnabled,
         ? new ProviderV2CompatibilityAdapter(new CopilotProviderV2(cli), turnPreparer)
         : new CopilotProviderAdapter(cli, turnPreparer);
 }
-function createCodexProvider(config, debugLogger, connectionsStateGateEnabled, turnPreparer) {
-    const cli = new CodexCliClient(config.codexCommand, config.codexArgs, {}, createProviderConnectionsSessionStore({
+function createCodexProvider(config, debugLogger, connectionsStateGateEnabled, turnPreparer, idleBackendShutdownMs) {
+    const cli = new CodexCliClient(config.codexCommand, config.codexArgs, { idleBackendShutdownMs }, createProviderConnectionsSessionStore({
         provider: 'codex',
         legacyStore: new FileCodexChannelSessionStore({
             resolvePath: (agentId) => resolveCodexSessionMapPath(config.stateRootDir, agentId),
@@ -112,6 +116,7 @@ export function createProvider(config, debugLogger, options = {}) {
     const skillRuntimeGateEnabled = routingConfig.compatibilityGates.has(SKILL_RUNTIME_COMPATIBILITY_GATE);
     const localhostGatewayGateEnabled = routingConfig.compatibilityGates.has(LOCALHOST_GATEWAY_COMPATIBILITY_GATE);
     const policyAuditGateEnabled = routingConfig.compatibilityGates.has(POLICY_AUDIT_ENFORCEMENT_COMPATIBILITY_GATE);
+    const idleBackendShutdownMs = resolveIdleBackendShutdownMs(config.providerIdleShutdownMinutes, routingConfig.compatibilityGates);
     const channelContextStore = contextInjectionGateEnabled
         ? new FileChannelContextStore(config.stateRootDir, {
             skillRuntimeEnabled: skillRuntimeGateEnabled,
@@ -124,16 +129,16 @@ export function createProvider(config, debugLogger, options = {}) {
     const turnPreparer = new ProviderTurnPreparer(channelContextStore, debugLogger);
     switch (config.provider) {
         case 'claude': {
-            return createClaudeProvider(config, debugLogger, connectionsStateGateEnabled, turnPreparer);
+            return createClaudeProvider(config, debugLogger, connectionsStateGateEnabled, turnPreparer, idleBackendShutdownMs);
         }
         case 'codex': {
             if (!routingConfig.compatibilityGates.has(CODEX_PROVIDER_COMPATIBILITY_GATE)) {
                 throw new Error(`Unsupported provider: ${String(config.provider)} (enable ${CODEX_PROVIDER_COMPATIBILITY_GATE})`);
             }
-            return createCodexProvider(config, debugLogger, connectionsStateGateEnabled, turnPreparer);
+            return createCodexProvider(config, debugLogger, connectionsStateGateEnabled, turnPreparer, idleBackendShutdownMs);
         }
         case 'copilot': {
-            return createCopilotProvider(config, debugLogger, connectionsStateGateEnabled, resolveCopilotImplementation(routingConfig), turnPreparer, policyAuditGateEnabled, options.authorizationAuditSink);
+            return createCopilotProvider(config, debugLogger, connectionsStateGateEnabled, resolveCopilotImplementation(routingConfig), turnPreparer, policyAuditGateEnabled, options.authorizationAuditSink, idleBackendShutdownMs);
         }
         default:
             throw new Error(`Unsupported provider: ${String(config.provider)}`);

package/dist/providers/idle-backend-shutdown.d.ts

@@ -0,0 +1,16 @@
+export declare const IDLE_BACKEND_SHUTDOWN_DISABLED_MS = 0;
+export declare function resolveIdleBackendShutdownMs(idleShutdownMinutes: number, compatibilityGates: ReadonlySet<string>): number;
+export interface IdleBackendShutdownSchedulerOptions {
+    idleShutdownMs: number;
+    isIdle: () => boolean;
+    shutdown: () => Promise<void>;
+    onShutdownFailed: (error: unknown) => void;
+}
+export declare class IdleBackendShutdownScheduler {
+    private readonly options;
+    private timer?;
+    constructor(options: IdleBackendShutdownSchedulerOptions);
+    get enabled(): boolean;
+    cancel(): void;
+    reconcile(): void;
+}

package/dist/providers/idle-backend-shutdown.js

@@ -0,0 +1,53 @@
+/**
+ * Idle shutdown policy for a provider's shared ACP adapter process.
+ *
+ * Every agent keeps one adapter child process resident across turns, so an
+ * agent nobody is talking to still pins a whole coding-CLI runtime in memory.
+ * The scheduler arms a timer whenever its owning client reports that no channel
+ * has work left, and hands the teardown back to the client once that timer
+ * expires; the client re-spawns the process lazily on the next turn.
+ *
+ * The `isIdle` probe is re-evaluated when the timer fires because a turn can
+ * arrive between arming and expiry, and the timer callback is the last point at
+ * which the shutdown can still be abandoned cheaply.
+ */
+import { PROVIDER_IDLE_SHUTDOWN_COMPATIBILITY_GATE } from '../compatibility-gates.js';
+export const IDLE_BACKEND_SHUTDOWN_DISABLED_MS = 0;
+export function resolveIdleBackendShutdownMs(idleShutdownMinutes, compatibilityGates) {
+    if (!compatibilityGates.has(PROVIDER_IDLE_SHUTDOWN_COMPATIBILITY_GATE)) {
+        return IDLE_BACKEND_SHUTDOWN_DISABLED_MS;
+    }
+    return idleShutdownMinutes * 60 * 1000;
+}
+export class IdleBackendShutdownScheduler {
+    options;
+    timer;
+    constructor(options) {
+        this.options = options;
+    }
+    get enabled() {
+        return this.options.idleShutdownMs > IDLE_BACKEND_SHUTDOWN_DISABLED_MS;
+    }
+    cancel() {
+        if (!this.timer) {
+            return;
+        }
+        clearTimeout(this.timer);
+        this.timer = undefined;
+    }
+    reconcile() {
+        this.cancel();
+        if (!this.enabled || !this.options.isIdle()) {
+            return;
+        }
+        this.timer = setTimeout(() => {
+            this.timer = undefined;
+            if (!this.options.isIdle()) {
+                return;
+            }
+            void this.options.shutdown().catch((error) => {
+                this.options.onShutdownFailed(error);
+            });
+        }, this.options.idleShutdownMs);
+    }
+}

package/dist/types.d.ts

@@ -7,6 +7,8 @@ export interface ProviderCommandConfig {
     copilotCommand: string;
     copilotArgs: string[];
     copilotSessionTtlMinutes: number;
+    /** Minutes a provider's shared ACP adapter process may stay idle before it is shut down; `0` keeps it resident. */
+    providerIdleShutdownMinutes: number;
 }
 export interface ProviderRuntimeConfig extends ProviderCommandConfig {
     provider: ProviderKind;
@@ -342,6 +344,11 @@ export interface ProviderReply {
     awaitingUser?: ProviderAwaitingUser;
     control?: ProviderTurnControl;
     controlMalformed?: boolean;
+    /**
+     * The provider session this turn ran in, when the provider exposes one.
+     * agents-host records it on the task as agent.session_id.
+     */
+    sessionId?: string;
 }
 export interface PostedMessage {
     messageId: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@borgee/agents-host",
-  "version": "0.2.33",
+  "version": "0.2.35",
   "private": false,
   "publishConfig": {
     "access": "public"
@@ -35,7 +35,7 @@
     "tsx": "^4.20.5",
     "typescript": "^5.9.3",
     "vitest": "^4.1.5",
-    "@borgee/plugin-sdk": "0.2.5"
+    "@borgee/plugin-sdk": "0.4.0"
   },
   "scripts": {
     "predev": "pnpm --filter @borgee/plugin-sdk build",

package/skills/borgee-agent/SKILL.md

@@ -25,11 +25,28 @@ Use one of the packaged local CLIs to inspect the current channel bootstrap payl
 
 The same CLIs also expose the task commands. Which ones apply depends on where the turn runs, which the injected `context.json` reports through `taskAssignmentContext`:
 
-- Parent channel (no `taskAssignmentContext.active`): `--create-task --title ...`, `--list-tasks`, `--get-task --task-id ...`, `--update-task --task-id ...`, `--read-task-history --task-id ...`
-- Task-assignment thread (`taskAssignmentContext.active: true`): `--get-task` and `--update-task` may omit `--task-id` and resolve the current thread task through the persisted `currentTaskId` or an agents-host local fallback; `--read-task-history --task-id ...` still works for that thread's own task, while `--create-task` and `--list-tasks` stay disabled and must be run from the parent channel
+- Parent channel (no `taskAssignmentContext.active`): `--create-task --title ...`, `--list-tasks`, `--get-task --task-id ...`, `--update-task --task-id ...`, `--read-task-history --task-id ...`, `--set-property <key>=<value> --task-id ...`, `--delete-property <key> --task-id ...`
+- Task-assignment thread (`taskAssignmentContext.active: true`): `--get-task`, `--update-task`, `--set-property` and `--delete-property` may omit `--task-id` and resolve the current thread task through the persisted `currentTaskId` or an agents-host local fallback; `--read-task-history --task-id ...` still works for that thread's own task, while `--create-task` and `--list-tasks` stay disabled and must be run from the parent channel
 
 `--read-task-history` reads the messages inside a task's thread and always requires an explicit `--task-id`; inside that task's own thread `--read-history` already reads the same messages, so the turn prompt offers the command in the parent channel only. It accepts the same `--limit` / `--before` / `--after` window as `--read-history` and answers the same not-found error for a task outside the current channel as for a task that does not exist.
 
+## Task properties
+
+A task property associates a task with something outside it. Use them to record what a reader would otherwise have to hunt for in the thread — the PR that implements the task, the issue it came from. Read them back with `--get-task`: every task response carries a `properties` object (`{}` when it has none).
+
+- Set: `node ./borgee-agent.mjs --context ... --auth-path ... --set-property "link.pr=https://github.com/org/repo/pull/12"`
+- Delete: `node ./borgee-agent.mjs --context ... --auth-path ... --delete-property "link.pr"`
+
+Pass `key=value` as ONE shell token so a value containing `=` survives intact. Each call writes exactly one key, which is what makes it safe to write a property while another agent is writing a different one on the same task — so never try to set several at once, just call again.
+
+Registered keys:
+
+- `link.pr` — the pull request implementing this task. Set it as soon as the PR exists, not at the end.
+- `link.issue` — the issue or ticket the task originates from.
+- `agent.session_id` — **do not write this**. agents-host records the provider session itself after each turn.
+
+An unregistered key is rejected; a value is a plain string capped at 8 KiB. Properties are references, not notes — anything that needs prose belongs in the task description or a thread message.
+
 The private draft snapshot is read-only, collaboration-scoped, and separate from ordinary public channel messages.
 Auxiliary sends are only for short targeted escalation, reply-thread nudges, or mentions. They must not be used for the main final answer body, which still belongs to AgentsHost.
 Both CLIs are local-only, may only access the loopback gateway described above, and must not mutate files.

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

@@ -3,7 +3,7 @@
 import { readFile } from 'node:fs/promises';
 
 const TASK_THREAD_COLLECTION_COMMAND_ERROR
-  = 'Task assignment threads only support --get-task and --update-task. Create/list tasks belong to the parent channel.';
+  = 'Task assignment threads only support --get-task, --update-task, --set-property and --delete-property. Create/list tasks belong to the parent channel.';
 const TASK_THREAD_MISSING_TASK_ID_ERROR
   = 'Task assignment thread could not resolve the current task from persisted context or local fallback. Pass --task-id explicitly.';
 // A window value outside the IEEE-754 safe integer range does not survive this CLI: it parses
@@ -28,6 +28,8 @@ function parseArgs(argv) {
   let assigneeId;
   let taskId;
   let status;
+  let propertyKey;
+  let propertyValue;
   const mentions = [];
 
   function setAction(nextAction) {
@@ -126,6 +128,32 @@ function parseArgs(argv) {
       setAction('update-task');
       continue;
     }
+    if (arg === '--set-property') {
+      setAction('set-property');
+      // key=value in one token so the pair cannot be split across flags and
+      // land half-applied.
+      const pair = argv[index + 1];
+      if (pair == null || !pair.includes('=')) {
+        throw new Error('--set-property requires <key>=<value>');
+      }
+      const separator = pair.indexOf('=');
+      propertyKey = pair.slice(0, separator);
+      propertyValue = pair.slice(separator + 1);
+      if (propertyKey.trim().length === 0) {
+        throw new Error('--set-property requires a non-empty key');
+      }
+      index += 1;
+      continue;
+    }
+    if (arg === '--delete-property') {
+      setAction('delete-property');
+      propertyKey = argv[index + 1];
+      if (propertyKey == null || propertyKey.trim().length === 0) {
+        throw new Error('--delete-property requires a key');
+      }
+      index += 1;
+      continue;
+    }
     if (arg === '--limit') {
       limit = parseIntegerOption(arg, argv[index + 1]);
       index += 1;
@@ -209,6 +237,8 @@ function parseArgs(argv) {
     assigneeId,
     taskId,
     status,
+    propertyKey: propertyKey?.trim(),
+    propertyValue,
   };
 }
 
@@ -370,6 +400,27 @@ function resolveGatewayRequest(payload, action, options) {
         usesCurrentThreadFallback: false,
       };
     }
+    case 'set-property':
+    case 'delete-property': {
+      const taskId = resolveTaskId(payload, action, options);
+      const method = action === 'set-property' ? 'PUT' : 'DELETE';
+      const requestBody = action === 'set-property' ? { value: options.propertyValue } : undefined;
+      const encodedKey = encodeURIComponent(String(options.propertyKey ?? ''));
+      if (payload.taskAssignmentContext?.active === true && explicitTaskId(options) === null) {
+        return {
+          url: new URL(`/v1/channels/${encodedChannelId}/current-task/properties/${encodedKey}`, gateway.baseUrl),
+          method,
+          body: requestBody,
+          usesCurrentThreadFallback: true,
+        };
+      }
+      return {
+        url: new URL(`/v1/tasks/${encodeURIComponent(taskId)}/properties/${encodedKey}`, gateway.baseUrl),
+        method,
+        body: requestBody,
+        usesCurrentThreadFallback: false,
+      };
+    }
     default:
       throw new Error(`Unsupported gateway action: ${action}`);
   }
@@ -480,6 +531,8 @@ const {
   assigneeId,
   taskId,
   status,
+  propertyKey,
+  propertyValue,
 } = parseArgs(process.argv.slice(2));
 const payload = JSON.parse(await readFile(contextPath, 'utf8'));
 
@@ -502,6 +555,8 @@ if (action === 'print-bootstrap') {
     assigneeId,
     taskId,
     status,
+    propertyKey,
+    propertyValue,
   });
   console.log(JSON.stringify(result, null, 2));
 }

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

@@ -11,8 +11,8 @@ from urllib.parse import quote, urlencode
 from urllib.request import Request, urlopen
 
 TASK_THREAD_COLLECTION_COMMAND_ERROR = (
-    "Task assignment threads only support --get-task and --update-task. "
-    "Create/list tasks belong to the parent channel."
+    "Task assignment threads only support --get-task, --update-task, --set-property "
+    "and --delete-property. Create/list tasks belong to the parent channel."
 )
 TASK_THREAD_MISSING_TASK_ID_ERROR = (
     "Task assignment thread could not resolve the current task from persisted context "
@@ -54,6 +54,8 @@ def parse_args(argv: list[str]) -> dict[str, object]:
     assignee_id: str | None = None
     task_id: str | None = None
     status: str | None = None
+    property_key: str | None = None
+    property_value: str | None = None
     index = 0
 
     def set_action(next_action: str) -> None:
@@ -155,6 +157,23 @@ def parse_args(argv: list[str]) -> dict[str, object]:
         elif arg == "--status":
             index += 1
             status = argv[index] if index < len(argv) else None
+        elif arg == "--set-property":
+            set_action("set-property")
+            index += 1
+            # key=value in one token so the pair cannot be split across flags
+            # and land half-applied.
+            pair = argv[index] if index < len(argv) else None
+            if pair is None or "=" not in pair:
+                raise ValueError("--set-property requires <key>=<value>")
+            property_key, property_value = pair.split("=", 1)
+            if not property_key.strip():
+                raise ValueError("--set-property requires a non-empty key")
+        elif arg == "--delete-property":
+            set_action("delete-property")
+            index += 1
+            property_key = argv[index] if index < len(argv) else None
+            if property_key is None or not property_key.strip():
+                raise ValueError("--delete-property requires a key")
         else:
             raise ValueError(f"Unknown argument: {arg}")
         index += 1
@@ -178,6 +197,8 @@ def parse_args(argv: list[str]) -> dict[str, object]:
         "assignee_id": assignee_id,
         "task_id": task_id,
         "status": status,
+        "property_key": property_key.strip() if isinstance(property_key, str) else None,
+        "property_value": property_value,
     }
 
 
@@ -303,6 +324,14 @@ def resolve_gateway_request(
         if isinstance(task_assignment_context, dict) and task_assignment_context.get("active") is True and explicit_task_id(options) is None:
             return f"{base_url}/v1/channels/{channel_id}/current-task", "PATCH", request_body, True
         return f"{base_url}/v1/tasks/{quote(str(task_id), safe='')}", "PATCH", request_body, False
+    if action in ("set-property", "delete-property"):
+        task_id = resolve_task_id(payload, action, options)
+        method = "PUT" if action == "set-property" else "DELETE"
+        request_body = {"value": options.get("property_value")} if action == "set-property" else None
+        encoded_key = quote(str(options.get("property_key") or ""), safe="")
+        if isinstance(task_assignment_context, dict) and task_assignment_context.get("active") is True and explicit_task_id(options) is None:
+            return f"{base_url}/v1/channels/{channel_id}/current-task/properties/{encoded_key}", method, request_body, True
+        return f"{base_url}/v1/tasks/{quote(str(task_id), safe='')}/properties/{encoded_key}", method, request_body, False
     raise ValueError(f"Unsupported gateway action: {action}")
 
 
@@ -431,6 +460,8 @@ else:
                     "assignee_id": parsed["assignee_id"],
                     "task_id": parsed["task_id"],
                     "status": parsed["status"],
+                    "property_key": parsed["property_key"],
+                    "property_value": parsed["property_value"],
                 },
             ),
             indent=2,