@borgee/agents-host 0.2.33 → 0.2.44

package/dist/gateway/localhost-gateway.js

@@ -505,6 +505,23 @@ class LoopbackLocalhostGatewayController {
                     this.recordAudit('authorized', 200, decision.path, request.method ?? 'GET', decision.binding);
                     return;
                 }
+                case 'current-task-property': {
+                    const task = await this.loadCurrentThreadTask(binding);
+                    const updatedTask = await this.applyTaskPropertyChange(request, task.id, decision.route.key);
+                    this.sendTaskPropertyResult(response, decision, binding.channelId, updatedTask, request.method);
+                    return;
+                }
+                case 'task-property': {
+                    // Load first: the write must be refused for a task outside the bound
+                    // channel BEFORE it lands, not reported as not-found afterwards.
+                    const task = await this.loadAuthorizedTask(binding.channelId, {
+                        taskId: decision.route.taskId,
+                        resource: 'task',
+                    });
+                    const updatedTask = await this.applyTaskPropertyChange(request, task.id, decision.route.key);
+                    this.sendTaskPropertyResult(response, decision, binding.channelId, updatedTask, request.method);
+                    return;
+                }
                 case 'task-history': {
                     // The thread this reads is the one the server recorded on the task: thread_id is
                     // written once by task creation and is not part of the task update whitelist, so no
@@ -612,9 +629,40 @@ class LoopbackLocalhostGatewayController {
         }
         return task;
     }
+    /**
+     * PUT writes the key, DELETE removes it. The method has already been
+     * narrowed to those two by the route's allowed-method table.
+     */
+    async applyTaskPropertyChange(request, taskId, key) {
+        try {
+            if (request.method === 'DELETE') {
+                return await this.controlPlane.deleteTaskProperty({ taskId, key });
+            }
+            const body = await readGatewayJsonBody(request);
+            return await this.controlPlane.setTaskProperty({ taskId, key, value: parseTaskPropertyValue(body) });
+        }
+        catch (error) {
+            throw mapGatewayControlPlaneError(error, 'authorized');
+        }
+    }
+    sendTaskPropertyResult(response, decision, boundChannelId, task, method) {
+        if (!isTaskInAuthorizedScope(boundChannelId, task)) {
+            this.sendJson(response, 404, { error: 'not_found' });
+            this.recordAudit('not-found', 404, decision.path, method ?? 'PUT', decision.binding);
+            return;
+        }
+        this.sendJson(response, 200, task);
+        this.recordAudit('authorized', 200, decision.path, method ?? 'PUT', decision.binding);
+    }
     async loadCurrentThreadTask(binding) {
+        // Only a task-thread binding has a current task at all. Without that context the scan below
+        // would list every visible channel's tasks to conclude what the binding already says, so the
+        // parent-channel answer is given here instead of after an O(channels x tasks) sweep.
+        if (binding.payload?.taskAssignmentContext?.active !== true) {
+            throw new GatewayHttpError(404, { error: 'not_found' }, 'not-found');
+        }
         let task;
-        const preferredTaskId = binding.payload?.taskAssignmentContext?.currentTaskId;
+        const preferredTaskId = binding.payload.taskAssignmentContext.currentTaskId;
         try {
             task = await findTaskForThread(this.controlPlane, binding.channelId, preferredTaskId);
         }
@@ -816,6 +864,17 @@ function parseUpdateTaskInput(taskId, body) {
     }
     return input;
 }
+/**
+ * The value is required and must be a string. An absent or non-string value is
+ * a caller bug, not an instruction to store the empty string — storing that
+ * would silently blank a key the caller meant to set.
+ */
+function parseTaskPropertyValue(body) {
+    if (!isRecord(body) || typeof body.value !== 'string') {
+        throw new GatewayHttpError(400, { error: 'invalid_property_value' }, 'bad-request');
+    }
+    return body.value;
+}
 function isTaskInAuthorizedScope(boundChannelId, task) {
     return task.channelId === boundChannelId || task.threadId === boundChannelId;
 }
@@ -846,6 +905,21 @@ function mapGatewayControlPlaneError(error, fallbackReason) {
             case 'bpp.channel_id_required':
             case 'bpp.task_id_required':
                 return new GatewayHttpError(400, { error: 'bad_request' }, 'bad-request');
+            // An unregistered key, an oversized value or a status outside the enum is the
+            // caller's own mistake. Falling through to 502 would tell the agent the server
+            // is broken, and it would retry the same bad call instead of correcting it.
+            case 'bpp.task_property_key_unknown':
+                return new GatewayHttpError(400, { error: 'unknown_property_key' }, 'bad-request');
+            case 'bpp.task_property_value_too_long':
+                return new GatewayHttpError(400, { error: 'property_value_too_long' }, 'bad-request');
+            case 'bpp.task_invalid_status':
+                return new GatewayHttpError(400, { error: 'invalid_status' }, 'bad-request');
+            // A distinct body, not the bare `not_found` the other routes use: on a
+            // current-task property request `not_found` means the thread's own task
+            // could not be resolved, and "pass the task id" is the wrong correction
+            // for a key that simply was not set.
+            case 'bpp.task_property_not_found':
+                return new GatewayHttpError(404, { error: 'property_not_found' }, 'not-found');
             default:
                 return new GatewayHttpError(502, { error: 'upstream_error' }, fallbackReason);
         }

package/dist/hosted-turn-content.d.ts

@@ -0,0 +1,15 @@
+import type { HostedMessageAttachment, HostedTurnContentPart } from './types.js';
+type CanonicalHostedMessageAttachment = HostedMessageAttachment & {
+    kind: NonNullable<HostedMessageAttachment['kind']>;
+};
+export declare function normalizeHostedMessageAttachment(attachment: HostedMessageAttachment): CanonicalHostedMessageAttachment;
+export declare function classifyHostedAttachmentKind(contentType: string | undefined): Extract<HostedTurnContentPart, {
+    type: 'image' | 'file';
+}>['type'];
+export declare function buildHostedTurnContentParts(input: {
+    text?: string;
+    attachments?: readonly HostedMessageAttachment[];
+}): HostedTurnContentPart[];
+export declare function extractHostedMessageAttachments(parts: readonly HostedTurnContentPart[]): HostedMessageAttachment[];
+export declare function buildHostedIncomingContentText(parts: readonly HostedTurnContentPart[]): string;
+export {};

package/dist/hosted-turn-content.js

@@ -0,0 +1,50 @@
+export function normalizeHostedMessageAttachment(attachment) {
+    return {
+        url: attachment.url,
+        ...(attachment.filename ? { filename: attachment.filename } : {}),
+        contentType: attachment.contentType,
+        kind: attachment.kind ?? classifyHostedAttachmentKind(attachment.contentType),
+        ...(attachment.sizeBytes !== undefined ? { sizeBytes: attachment.sizeBytes } : {}),
+    };
+}
+export function classifyHostedAttachmentKind(contentType) {
+    return contentType?.toLowerCase().startsWith('image/') ? 'image' : 'file';
+}
+export function buildHostedTurnContentParts(input) {
+    const text = input.text?.trim() ?? '';
+    const attachments = input.attachments ?? [];
+    const parts = [];
+    if (text.length > 0) {
+        parts.push({ type: 'text', text });
+    }
+    for (const attachment of attachments) {
+        const normalizedAttachment = normalizeHostedMessageAttachment(attachment);
+        parts.push({
+            type: normalizedAttachment.kind,
+            attachment: normalizedAttachment,
+        });
+    }
+    return parts;
+}
+export function extractHostedMessageAttachments(parts) {
+    return parts.flatMap((part) => ('attachment' in part ? [normalizeHostedMessageAttachment(part.attachment)] : []));
+}
+export function buildHostedIncomingContentText(parts) {
+    const text = parts
+        .flatMap((part) => (part.type === 'text' ? [part.text] : []))
+        .join('\n')
+        .trim();
+    const nonTextParts = parts.filter((part) => part.type === 'image' || part.type === 'file');
+    if (nonTextParts.length === 0) {
+        return text;
+    }
+    const summaryLines = [
+        `[Attachment metadata was received for ${nonTextParts.length} attachment${nonTextParts.length === 1 ? '' : 's'}]`,
+        ...nonTextParts.map((part, index) => {
+            const filename = part.attachment.filename?.trim();
+            return `${index + 1}. ${part.type};${filename ? ` filename: ${filename};` : ''} content type: ${part.attachment.contentType}`;
+        }),
+    ];
+    const summary = summaryLines.join('\n');
+    return text ? `${text}\n\n${summary}` : summary;
+}

package/dist/local-config.js

@@ -2,7 +2,7 @@ import { promises as fs } from 'node:fs';
 import { randomUUID } from 'node:crypto';
 import { dirname, extname, isAbsolute, join, relative, resolve } from 'node:path';
 import { parseDocument, stringify } from 'yaml';
-import { assertProviderCompatibility, assertProviderCommandCompatibility, optionalNonEmptyString, optionalStringArray, parseCopilotSessionTtlMinutesValue, requireNonEmptyString, resolveProvider, resolveProviderCommandConfig, } from './config.js';
+import { assertProviderCompatibility, assertProviderCommandCompatibility, optionalNonEmptyString, optionalStringArray, parseCopilotSessionTtlMinutesValue, parseProviderIdleShutdownMinutesValue, requireNonEmptyString, resolveProvider, resolveProviderCommandConfig, } from './config.js';
 import { resolveLocalConfigAgentStateRoot } from './state-paths.js';
 const SUPPORTED_CONFIG_EXTENSIONS = new Set(['.json', '.yaml', '.yml']);
 export const DEFAULT_LOCAL_HOST_CONFIG_FILENAME = 'agents-host.yaml';
@@ -124,6 +124,9 @@ function parseProviderCommandOverrides(value, sourceLabel) {
     if (value.copilotSessionTtlMinutes !== undefined && value.copilotSessionTtlMinutes !== null) {
         overrides.copilotSessionTtlMinutes = parseCopilotSessionTtlMinutesValue(value.copilotSessionTtlMinutes, sourceLabel);
     }
+    if (value.providerIdleShutdownMinutes !== undefined && value.providerIdleShutdownMinutes !== null) {
+        overrides.providerIdleShutdownMinutes = parseProviderIdleShutdownMinutesValue(value.providerIdleShutdownMinutes, sourceLabel);
+    }
     return overrides;
 }
 function toAgentsDir(hostConfigPath, rawAgentsDir) {
@@ -593,6 +596,9 @@ function renderAgentConfigYaml(agent) {
     if (agent.copilotSessionTtlMinutes !== undefined) {
         config.copilotSessionTtlMinutes = agent.copilotSessionTtlMinutes;
     }
+    if (agent.providerIdleShutdownMinutes !== undefined) {
+        config.providerIdleShutdownMinutes = agent.providerIdleShutdownMinutes;
+    }
     return stringify(config);
 }
 function buildManagedAgentSnapshot(host, stateRootBaseDir, sourcePath, agent) {
@@ -629,6 +635,9 @@ function resolveAgentProviderCommandConfig(hostDefaults, agent) {
         ...(agent.copilotSessionTtlMinutes !== undefined
             ? { copilotSessionTtlMinutes: agent.copilotSessionTtlMinutes }
             : {}),
+        ...(agent.providerIdleShutdownMinutes !== undefined
+            ? { providerIdleShutdownMinutes: agent.providerIdleShutdownMinutes }
+            : {}),
     });
 }
 export async function loadLocalConfigSnapshot(hostConfigPath, deps = {}) {

package/dist/managed-daemon.d.ts

@@ -95,6 +95,7 @@ export interface ManagedAgentsHostDaemonDeps {
     materialize?: (rootPath: string, spec: LocalConfigGenerateSpec) => Promise<unknown>;
     logger?: Pick<Console, 'log' | 'error'>;
     logPath?: string;
+    platform?: NodeJS.Platform;
 }
 export interface DescribeManagedSpecOptions {
     serverUrl: string;
@@ -192,7 +193,7 @@ export declare function applyManagedSpec(options: ApplyManagedSpecOptions, deps?
 export declare class ManagedAgentsHostDaemon {
     private readonly rootPath;
     private readonly hostConfigPath;
-    private readonly socketPath;
+    private readonly endpoint;
     private readonly createSupervisor;
     private readonly supervisor;
     private readonly loadSpec;
@@ -204,7 +205,7 @@ export declare class ManagedAgentsHostDaemon {
     private requestQueue;
     private started;
     private ready;
-    private ownsSocket;
+    private ownsEndpoint;
     private shutdownRequested;
     private ownedSocketInode;
     constructor(rootPath: string, debug?: boolean, deps?: ManagedAgentsHostDaemonDeps);

package/dist/managed-daemon.js

@@ -8,7 +8,7 @@ import { AgentsHostSupervisor } from './agents-host-supervisor.js';
 import { CLAUDE_PROVIDER_V2_COMPATIBILITY_GATE, COMPATIBILITY_GATES_ENV, createManagedRuntimeSettingsFingerprint, INTERNAL_DISABLED_COMPATIBILITY_GATES_ENV, INTERNAL_POLICY_MODE_ENV, INTERNAL_PROVIDER_IMPLEMENTATIONS_ENV, MANAGED_RUNTIME_CONVERGENCE_COMPATIBILITY_GATE, MANAGED_RUNTIME_SETTINGS_SCHEMA_VERSION, resolveDisabledDefaultCompatibilityGates, resolveManagedRuntimeSettingsSnapshot, normalizeInternalProviderImplementationOverrides, } from './compatibility-gates.js';
 import { DEFAULT_PROVIDER_COMMAND_CONFIG, hasLegacyClaudeOneShotArgs, loadConfigFromEnv, } from './config.js';
 import { loadLocalConfigGenerateSpec, materializeLocalConfig, parseGenerateConfigSpec, resolveLocalConfigLayout, } from './local-config.js';
-import { normalizeManagedRuntimeKey, resolveManagedBootstrapLockPath, resolveManagedDaemonLogPath, resolveManagedDaemonSocketPath, resolveManagedRuntimeRoot, resolveManagedRuntimeSettingsPath, } from './state-paths.js';
+import { normalizeManagedRuntimeKey, resolveManagedBootstrapLockPath, resolveManagedDaemonEndpoint, resolveManagedDaemonLogPath, resolveManagedRuntimeRoot, resolveManagedRuntimeSettingsPath, } from './state-paths.js';
 const MANAGED_ROOT_MODE = 0o700;
 const MANAGED_CONFIG_MODE = 0o600;
 const BOOTSTRAP_LOCK_WAIT_MS = 10_000;
@@ -339,6 +339,7 @@ export function buildManagedLocalAgentConfig(options) {
             copilotCommand: config.copilotCommand,
             copilotArgs: [...config.copilotArgs],
             copilotSessionTtlMinutes: config.copilotSessionTtlMinutes,
+            providerIdleShutdownMinutes: config.providerIdleShutdownMinutes,
         },
     };
 }
@@ -382,6 +383,9 @@ function mergeManagedLocalAgentConfig(hostDefaults, existingAgent, generatedAgen
         copilotSessionTtlMinutes: hasOverride('COPILOT_SESSION_TTL_MINUTES')
             ? generatedAgent.copilotSessionTtlMinutes
             : existingAgent.copilotSessionTtlMinutes,
+        providerIdleShutdownMinutes: hasOverride('PROVIDER_IDLE_SHUTDOWN_MINUTES')
+            ? generatedAgent.providerIdleShutdownMinutes
+            : existingAgent.providerIdleShutdownMinutes,
     };
 }
 function collectExplicitManagedAgentEnvOverrides(processEnv, optionEnv) {
@@ -396,6 +400,7 @@ function collectExplicitManagedAgentEnvOverrides(processEnv, optionEnv) {
         'COPILOT_COMMAND',
         'COPILOT_ARGS',
         'COPILOT_SESSION_TTL_MINUTES',
+        'PROVIDER_IDLE_SHUTDOWN_MINUTES',
     ]) {
         if (processEnv[key] !== undefined) {
             explicitOverrides[key] = processEnv[key];
@@ -594,8 +599,11 @@ async function canConnectToSocket(socketPath) {
         socket.once('error', () => finalize(false));
     });
 }
-async function removeStaleControlSocket(socketPath) {
-    const stats = await fs.lstat(socketPath).catch((error) => {
+async function removeStaleControlSocket(endpoint) {
+    if (endpoint.kind === 'named-pipe') {
+        return false;
+    }
+    const stats = await fs.lstat(endpoint.address).catch((error) => {
         if (isNotFoundError(error)) {
             return undefined;
         }
@@ -605,15 +613,15 @@ async function removeStaleControlSocket(socketPath) {
         return false;
     }
     if (stats.isDirectory() || stats.isSymbolicLink()) {
-        throw new Error(`Managed control socket path has an unexpected value: ${socketPath}`);
+        throw new Error(`Managed control socket path has an unexpected value: ${endpoint.address}`);
     }
-    if (await canConnectToSocket(socketPath)) {
+    if (await canConnectToSocket(endpoint.address)) {
         return false;
     }
     if (!stats.isSocket() && !stats.isFile()) {
-        throw new Error(`Managed control socket path has an unexpected value: ${socketPath}`);
+        throw new Error(`Managed control socket path has an unexpected value: ${endpoint.address}`);
     }
-    await fs.rm(socketPath, { force: true });
+    await fs.rm(endpoint.address, { force: true });
     return true;
 }
 function parseDaemonResponse(raw) {
@@ -650,12 +658,12 @@ function isManagedDaemonConnectionError(error) {
         isNodeErrorWithCode(error, 'ECONNRESET'));
 }
 export async function sendManagedDaemonRequest(rootPath, request) {
-    const socketPath = resolveManagedDaemonSocketPath(rootPath);
+    const endpoint = resolveManagedDaemonEndpoint(rootPath);
     const requestTimeoutMs = request.type === 'upsertAgent' || request.type === 'applySpec'
         ? DAEMON_RECONCILE_WAIT_MS
         : DAEMON_READY_WAIT_MS;
     return new Promise((resolveRequest, rejectRequest) => {
-        const socket = createConnection(socketPath);
+        const socket = createConnection(endpoint.address);
         let settled = false;
         let responseBuffer = '';
         const rejectOnce = (error) => {
@@ -676,7 +684,7 @@ export async function sendManagedDaemonRequest(rootPath, request) {
         };
         socket.setEncoding('utf8');
         socket.setTimeout(requestTimeoutMs);
-        socket.once('timeout', () => rejectOnce(new Error(`Timed out talking to managed daemon: ${socketPath}`)));
+        socket.once('timeout', () => rejectOnce(new Error(`Timed out talking to managed daemon: ${endpoint.address}`)));
         socket.once('error', rejectOnce);
         socket.on('data', (chunk) => {
             responseBuffer += chunk;
@@ -785,9 +793,9 @@ async function readReadyManagedDaemonStatus(rootPath, sendRequest) {
 }
 async function waitForManagedDaemonShutdown(rootPath, canConnect) {
     const deadline = Date.now() + DAEMON_READY_WAIT_MS;
-    const socketPath = resolveManagedDaemonSocketPath(rootPath);
+    const endpoint = resolveManagedDaemonEndpoint(rootPath);
     while (Date.now() < deadline) {
-        const listening = await canConnect(socketPath).catch((error) => {
+        const listening = await canConnect(endpoint.address).catch((error) => {
             if (isNodeErrorWithCode(error, 'ENOENT')) {
                 return false;
             }
@@ -1476,7 +1484,7 @@ export async function applyManagedSpec(options, deps = {}) {
 export class ManagedAgentsHostDaemon {
     rootPath;
     hostConfigPath;
-    socketPath;
+    endpoint;
     createSupervisor;
     supervisor;
     loadSpec;
@@ -1488,14 +1496,14 @@ export class ManagedAgentsHostDaemon {
     requestQueue = Promise.resolve();
     started = false;
     ready = false;
-    ownsSocket = false;
+    ownsEndpoint = false;
     shutdownRequested = false;
     ownedSocketInode = null;
     constructor(rootPath, debug = false, deps = {}) {
         const layout = resolveLocalConfigLayout(rootPath);
         this.rootPath = layout.root;
         this.hostConfigPath = layout.hostConfigPath;
-        this.socketPath = resolveManagedDaemonSocketPath(this.rootPath);
+        this.endpoint = resolveManagedDaemonEndpoint(this.rootPath, deps.platform);
         this.createSupervisor =
             deps.createSupervisor ??
                 ((configPath, daemonDebug) => new AgentsHostSupervisor(configPath, { debug: daemonDebug }));
@@ -1530,22 +1538,34 @@ export class ManagedAgentsHostDaemon {
             this.logger.log('[agents-host] managed daemon ready', {
                 rootPath: this.rootPath,
                 hostConfigPath: this.hostConfigPath,
-                socketPath: this.socketPath,
+                socketPath: this.endpoint.address,
             });
         }
         catch (error) {
             this.started = false;
             this.ready = false;
-            await this.stop().catch(() => undefined);
+            try {
+                await this.stop();
+            }
+            catch (cleanupError) {
+                this.logger.error('[agents-host] managed daemon startup cleanup failed', {
+                    rootPath: this.rootPath,
+                    error: cleanupError,
+                });
+            }
             throw error;
         }
     }
     async stop() {
         this.ready = false;
+        let stopError;
         try {
             await this.supervisor.stop();
         }
-        finally {
+        catch (error) {
+            stopError = error;
+        }
+        try {
             await new Promise((resolveStop) => {
                 if (!this.server.listening) {
                     resolveStop();
@@ -1553,17 +1573,38 @@ export class ManagedAgentsHostDaemon {
                 }
                 this.server.close(() => resolveStop());
             });
-            if (this.ownsSocket) {
-                const socketStats = await fs.lstat(this.socketPath).catch(() => undefined);
+            if (this.ownsEndpoint && this.endpoint.kind === 'unix-socket') {
+                const socketStats = await fs.lstat(this.endpoint.address).catch((error) => {
+                    if (isNotFoundError(error)) {
+                        return undefined;
+                    }
+                    throw error;
+                });
                 if (socketStats && socketStats.ino === this.ownedSocketInode) {
-                    await fs.rm(this.socketPath, { force: true }).catch(() => undefined);
+                    await fs.rm(this.endpoint.address, { force: true });
                 }
-                this.ownsSocket = false;
-                this.ownedSocketInode = null;
             }
+        }
+        catch (cleanupError) {
+            if (stopError) {
+                this.logger.error('[agents-host] managed daemon control endpoint cleanup failed', {
+                    rootPath: this.rootPath,
+                    error: cleanupError,
+                });
+            }
+            else {
+                stopError = cleanupError;
+            }
+        }
+        finally {
+            this.ownsEndpoint = false;
+            this.ownedSocketInode = null;
             this.started = false;
             this.shutdownRequested = false;
         }
+        if (stopError) {
+            throw stopError;
+        }
     }
     async listen() {
         for (let attempt = 0; attempt < 2; attempt++) {
@@ -1579,20 +1620,32 @@ export class ManagedAgentsHostDaemon {
                     };
                     this.server.once('error', onError);
                     this.server.once('listening', onListening);
-                    this.server.listen(this.socketPath);
+                    this.server.listen(this.endpoint.address);
                 });
-                await fs.chmod(this.socketPath, MANAGED_CONFIG_MODE);
-                this.ownedSocketInode = (await fs.lstat(this.socketPath)).ino;
-                this.ownsSocket = true;
+                if (this.endpoint.kind === 'unix-socket') {
+                    await fs.chmod(this.endpoint.address, MANAGED_CONFIG_MODE);
+                    this.ownedSocketInode = (await fs.lstat(this.endpoint.address)).ino;
+                }
+                this.ownsEndpoint = true;
                 return;
             }
             catch (error) {
-                if (!isSocketBusyError(error) || !(await removeStaleControlSocket(this.socketPath))) {
+                if (!isSocketBusyError(error)) {
+                    throw error;
+                }
+                if (this.endpoint.kind === 'named-pipe') {
+                    if (await canConnectToSocket(this.endpoint.address)) {
+                        throw error;
+                    }
+                    await delay(DAEMON_READY_RETRY_MS);
+                    continue;
+                }
+                if (!(await removeStaleControlSocket(this.endpoint))) {
                     throw error;
                 }
             }
         }
-        throw new Error(`Unable to bind managed daemon control socket: ${this.socketPath}`);
+        throw new Error(`Unable to bind managed daemon control endpoint: ${this.endpoint.address}`);
     }
     async handleSocket(socket) {
         let buffer = '';

package/dist/plugin-sdk.js

@@ -4729,6 +4729,12 @@ function encodeActionPayload(action) {
         ...action.heartbeat_interval_ms !== void 0 ? { heartbeat_interval_ms: action.heartbeat_interval_ms } : {},
         ...action.heartbeat_prompt !== void 0 ? { heartbeat_prompt: action.heartbeat_prompt } : {}
       };
+    case "set_task_property":
+      return { task_id: action.taskId, key: action.key, value: action.value };
+    case "delete_task_property":
+      return { task_id: action.taskId, key: action.key };
+    case "list_task_property_definitions":
+      return {};
     default:
       return {};
   }
@@ -4795,7 +4801,17 @@ function decodeActionResult(op, payloadJSON, frameCursor) {
     case "create_task":
     case "get_task":
     case "update_task":
+    case "set_task_property":
+    case "delete_task_property":
       return decodeTask(p);
+    case "list_task_property_definitions": {
+      const arr = Array.isArray(p) ? p : [];
+      return arr.map((d) => ({
+        key: String(d.key ?? ""),
+        label: String(d.label ?? ""),
+        render: d.render === "url" || d.render === "identifier" ? d.render : "text"
+      }));
+    }
     case "list_tasks": {
       const arr = Array.isArray(p) ? p : [];
       return arr.map(decodeTask);
@@ -4809,6 +4825,7 @@ function decodeTask(t) {
     id: String(t.id ?? ""),
     channelId: String(t.channel_id ?? ""),
     guildId: String(t.guild_id ?? ""),
+    seq: Number(t.seq ?? 0),
     title: String(t.title ?? ""),
     description: String(t.description ?? ""),
     status: String(t.status ?? ""),
@@ -4818,9 +4835,23 @@ function decodeTask(t) {
     messageId: t.message_id != null ? String(t.message_id) : null,
     threadId: t.thread_id != null ? String(t.thread_id) : null,
     createdAt: Number(t.created_at ?? 0),
-    updatedAt: Number(t.updated_at ?? 0)
+    updatedAt: Number(t.updated_at ?? 0),
+    heartbeatIntervalMs: Number(t.heartbeat_interval_ms ?? 0),
+    heartbeatPrompt: String(t.heartbeat_prompt ?? ""),
+    participants: Array.isArray(t.participants) ? t.participants.map((p) => String(p)) : [],
+    properties: decodeTaskProperties(t.properties)
   };
 }
+function decodeTaskProperties(raw) {
+  if (raw == null || typeof raw !== "object" || Array.isArray(raw))
+    return {};
+  const out = {};
+  for (const [key, value] of Object.entries(raw)) {
+    if (typeof value === "string")
+      out[key] = value;
+  }
+  return out;
+}
 function mapInbound(frame) {
   const kind = frame.kind;
   const base = {
@@ -5068,6 +5099,32 @@ var Client = class {
       heartbeat_prompt: input.heartbeatPrompt
     });
   }
+  // ─── Task properties ────────────────────────────────────
+  // One key per call. The server has no whole-object property write, so two
+  // agents writing different keys of the same task never overwrite each other.
+  async setTaskProperty(input) {
+    return await this.t.perform({
+      op: "set_task_property",
+      taskId: input.taskId,
+      key: input.key,
+      value: input.value
+    });
+  }
+  async deleteTaskProperty(input) {
+    return await this.t.perform({
+      op: "delete_task_property",
+      taskId: input.taskId,
+      key: input.key
+    });
+  }
+  /**
+   * The registered property keys with their labels and render kinds. Read this
+   * rather than hardcoding keys — the server can register a new property
+   * without an SDK release.
+   */
+  async listTaskPropertyDefinitions() {
+    return await this.t.perform({ op: "list_task_property_definitions" });
+  }
   startTyping(channelId) {
     const emit = () => {
       void this.t.perform({ op: "report_typing", channelId }).catch((err) => this.logger.warn("startTyping failed", err));