@borgee/agents-host 0.2.44 → 0.2.62

package/dist/types.d.ts

@@ -1,4 +1,5 @@
 export type ProviderKind = 'claude' | 'codex' | 'copilot';
+export type ProjectionStrategy = 'session-brief' | 'turn-full' | 'message-only' | 'turn-thin' | 'file-brief';
 export interface ProviderCommandConfig {
     claudeCommand: string;
     claudeArgs: string[];
@@ -9,6 +10,12 @@ export interface ProviderCommandConfig {
     copilotSessionTtlMinutes: number;
     /** Minutes a provider's shared ACP adapter process may stay idle before it is shut down; `0` keeps it resident. */
     providerIdleShutdownMinutes: number;
+    /**
+     * Whether this agents-host may let a hosted agent enter an independent
+     * execution.local_directory workspace for a task thread created by another
+     * agent. Undefined keeps the default allow behavior.
+     */
+    allowCrossAgentIndependentWorkspaceHandoff?: boolean;
 }
 export interface ProviderRuntimeConfig extends ProviderCommandConfig {
     provider: ProviderKind;
@@ -167,7 +174,7 @@ export interface CollaborationDraftSnapshot {
 }
 export type ProviderCollaborationTurnMode = 'ordinary' | 'silent-kickoff' | 'protocol-managed';
 export type CollaborationOutcomeResponseState = 'responded' | 'blocked' | 'superseded' | 'failed';
-export type CollaborationOutcomeDeliveryState = 'posted' | 'draft-finalized' | 'not-delivered' | 'delivery-failed';
+export type CollaborationOutcomeDeliveryState = 'posted' | 'not-delivered' | 'delivery-failed';
 export type CollaborationOutcomeWakeState = 'waiting' | 'suppressed-agent' | 'resumed-human';
 export interface CollaborationOutcomeBlockedDetails {
     question: string;
@@ -211,6 +218,22 @@ export interface AttentionSnapshot {
     turnExecutionId?: string;
     claimContext?: AttentionClaimContext;
 }
+export type ProviderCompactionStage = 'started' | 'completed' | 'failed';
+/**
+ * Shared host-side projection only. This is the latest host-observed compaction
+ * lifecycle snapshot surfaced by a provider adapter; it is not provider- or
+ * model-authoritative truth about retained prompt content.
+ */
+export interface CompactionSnapshot {
+    source: 'host-observed';
+    provider: ProviderKind;
+    stage: ProviderCompactionStage;
+    observedAt: number;
+    turnExecutionId?: string;
+    usedTokens?: number;
+    contextWindowTokens?: number;
+    failureReason?: string;
+}
 export type TaskThreadCollaborationTurnRole = 'assignment' | 'continuation';
 export type TaskThreadMainResultContract = 'ordinary-final-reply-in-thread';
 export type TaskThreadAuxiliaryRouteContract = 'optional-auxiliary-send-or-escalation-only';
@@ -233,6 +256,7 @@ export interface TaskThreadCollaborationContract {
 export interface CollaborationCapabilityDeclaration {
     collaborationOutcome?: true;
     attentionSnapshot?: true;
+    compactionSnapshot?: true;
     taskThreadCollaborationContract?: true;
     missedCollaborationDiagnostic?: true;
     recoveryExplanation?: 'runtime-local-only';
@@ -264,9 +288,12 @@ export interface ProviderInput {
     collaboration?: ProviderCollaborationContext;
     collaborationOutcome?: CollaborationOutcomeSnapshot;
     attentionSnapshot?: AttentionSnapshot;
+    compactionSnapshot?: CompactionSnapshot;
     taskThreadCollaborationContract?: TaskThreadCollaborationContract;
     collaborationCapabilities?: CollaborationCapabilityDeclaration;
     missedCollaborationDiagnostic?: MissedCollaborationDiagnostic;
+    taskAssignmentContextOverride?: TaskAssignmentThreadContext;
+    taskAssignmentContextOverridePersistence?: 'persist' | 'ephemeral';
 }
 export interface ProviderProtocolContext {
     anchorMessageId: string;
@@ -310,17 +337,57 @@ export interface TaskAssignmentThreadContext {
     active: true;
     currentTaskId?: string;
 }
-export interface TaskWorkspaceContext {
-    currentTaskId: string;
+export interface ChannelResolvedWorkspaceContext {
+    authority: 'channel';
+    owningChannelId: string;
     rootPath: string;
 }
+export interface TaskThreadScratchWorkspaceContext {
+    authority: 'task-thread-scratch';
+    rootPath: string;
+    reason?: 'missing-or-invalid-execution-target' | 'cross-agent-independent-workspace-disabled';
+}
+export interface TaskExecutionTargetResolvedWorkspaceContext {
+    authority: 'task-execution-target';
+    taskId: string;
+    rootPath: string;
+}
+export type ResolvedWorkspaceContext = ChannelResolvedWorkspaceContext | TaskThreadScratchWorkspaceContext | TaskExecutionTargetResolvedWorkspaceContext;
+export interface RuntimeSurface {
+    schemaVersion: 1;
+    turnMode: ProviderCollaborationTurnMode;
+    gateway: {
+        available: boolean;
+        readOnlyRoutesAuthorized: boolean;
+        inspectBeforeAnswer: boolean;
+    };
+    task: {
+        currentThread: 'parent-channel' | 'task-assignment-thread';
+        parentChannelTaskCollection: 'available' | 'parent-channel-only';
+        currentTaskShorthand: 'requires-task-id' | 'persisted-current-task' | 'fallback-current-task';
+        currentTaskIdPersisted: boolean;
+        currentTaskFallback: 'disallowed' | 'visible-parent-channel-thread-scan';
+    };
+    collaboration: {
+        participantLookup: 'unavailable' | 'available';
+        draftRead: 'unavailable' | 'available';
+        auxiliarySend: 'unavailable' | 'available';
+    };
+    response: {
+        mainVisibleReply: 'model-visible-reply' | 'host-visible-protocol-reply' | 'no-visible-reply';
+        auxiliaryMessageUsage: 'unavailable' | 'targeted-escalation-only';
+    };
+}
 export interface PreparedPromptContext {
     channelContextPayloadPath?: string;
+    claudeProjectedBriefPath?: string;
+    claudeProjectedBriefHash?: string;
     gatewayCredentialPath?: string;
     collaborationTurnExecutionId?: string;
     collaborationTurnMode?: ProviderCollaborationTurnMode;
     collaborationOutcome?: CollaborationOutcomeSnapshot;
     attentionSnapshot?: AttentionSnapshot;
+    compactionSnapshot?: CompactionSnapshot;
     taskThreadCollaborationContract?: TaskThreadCollaborationContract;
     collaborationCapabilities?: CollaborationCapabilityDeclaration;
     missedCollaborationDiagnostic?: MissedCollaborationDiagnostic;
@@ -330,19 +397,25 @@ export interface PreparedPromptContext {
     skillRuntime?: SkillRuntimeBootstrapMetadata;
     localhostGateway?: LocalhostGatewayBootstrapMetadata;
     taskAssignmentContext?: TaskAssignmentThreadContext;
-    taskWorkspace?: TaskWorkspaceContext;
+    resolvedWorkspace?: ResolvedWorkspaceContext;
+    runtimeSurface?: RuntimeSurface;
 }
 export interface PreparedProviderSessionRouting {
     key: string;
     persistence: 'persistent' | 'ephemeral';
 }
 export interface PreparedProviderTurnInput {
+    agentName?: string;
     channelId: string;
     incomingContent: string;
     incomingParts: HostedTurnContentPart[];
     incomingEventKind?: string;
     incomingMessageType?: string;
     prompt: string;
+    /** Claude-only session append content for ACP systemPrompt.append. */
+    claudeSessionPromptAppend?: string;
+    /** Shared projection-strategy selector used for provider prompt/session experiments. */
+    projectionStrategy?: ProjectionStrategy;
     promptContext?: PreparedPromptContext;
     providerSessionRouting?: PreparedProviderSessionRouting;
 }
@@ -417,9 +490,73 @@ export interface UpdateTaskInput {
     title?: string;
     description?: string;
 }
-export interface ProviderProgressUpdate {
-    text: string;
+/** The protocol's ten tool kinds, treated as open: an unknown value is not an error. */
+export type ProgressActivityKind = 'read' | 'edit' | 'delete' | 'move' | 'search' | 'execute' | 'think' | 'fetch' | 'switch_mode' | 'other';
+/** The protocol's four statuses, plus the one it lacks: stopped, waiting on a human. */
+export type ProgressActivityStatus = 'pending' | 'in_progress' | 'waiting' | 'completed' | 'failed';
+/**
+ * One entry in an agent's timeline of work. Identity is minted by the producer:
+ * a producer that can correlate later progress to an earlier event reuses the
+ * id and the entry is patched in place; one that cannot mints a fresh id and
+ * entries accumulate. An absent field means unchanged; `paths` replaces.
+ */
+export interface ProgressActivity {
+    id: string;
+    /** The protocol's title. For a shell tool this is the raw command line. */
+    label?: string;
+    /** The provider's human-readable phrasing, when it offers one. */
+    description?: string;
+    kind?: ProgressActivityKind;
+    status?: ProgressActivityStatus;
+    /** Bounded one-line detail: the command, the file, the query. Never raw output. */
+    detail?: string;
+    /** Files this activity touched. Replaces the previous list. */
+    paths?: string[];
+    /** The activity that spawned this one. */
+    parentId?: string;
+    /**
+     * Whether this activity is a container for other work rather than work of its
+     * own. A reader nests under it, and cannot arrive at that by noticing it has
+     * children: a sub-agent's children can be reported before it is, and a
+     * sub-agent that has spawned nothing yet is still a sub-agent.
+     */
+    subagent?: boolean;
+    /** Why a terminal activity ended as it did. An open set upstream, so never an enum. */
+    reason?: string;
+}
+/** Plan entries have no identity: the whole list is replaced on every update. */
+export interface ProgressPlanItem {
+    label: string;
+    status: 'pending' | 'in_progress' | 'completed';
+}
+export interface ProviderCompactionProgress {
+    provider: ProviderKind;
+    stage: ProviderCompactionStage;
+    usedTokens?: number;
+    contextWindowTokens?: number;
+    failureReason?: string;
 }
+/**
+ * A plan, a tool call and a stream of text are three meanings with three
+ * cardinalities and three update rules, so they travel as three shapes rather
+ * than as one entry with a category field. Text is cumulative rather than a
+ * delta, so a consumer that misses one update recovers on the next.
+ */
+export type ProviderProgressUpdate = {
+    type: 'text';
+    stream: 'answer' | 'reasoning';
+    text: string;
+    messageId?: string;
+} | {
+    type: 'activity';
+    activity: ProgressActivity;
+} | {
+    type: 'plan';
+    items: ProgressPlanItem[];
+} | {
+    type: 'compaction';
+    compaction: ProviderCompactionProgress;
+};
 export interface ProviderGenerateOptions {
     onProgress?: (update: ProviderProgressUpdate) => void;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@borgee/agents-host",
-  "version": "0.2.44",
+  "version": "0.2.62",
   "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.4.0"
+    "@borgee/plugin-sdk": "0.12.0"
   },
   "scripts": {
     "predev": "pnpm --filter @borgee/plugin-sdk build",

package/skills/borgee-agent/SKILL.md

@@ -11,6 +11,14 @@ This turn is running as an agent inside a Borgee channel. The packaged CLI is th
 
 Every command below is already authorized on a turn whose prompt names a gateway credential file. Run it directly. Never ask the user for permission first, and never end a turn having asked to read instead of reading.
 
+## Session contract
+
+This session is the coordination surface for the work that belongs to this Borgee thread: read the channel, answer the human here, break the work down, and keep task state current here.
+
+Delegate the heavy execution to workers rather than running everything inline in this session. Research, code edits, long builds and test runs, and broad repository sweeps belong in delegated workers so a newly arriving message can still be handled promptly here.
+
+Delegation changes who executes, not who owns. The work still belongs to this thread, and this session still reports the result here itself.
+
 ## When to use it
 
 - You are asked what was said here, who is here, or what you are supposed to be working on: read it, do not guess.
@@ -56,15 +64,15 @@ Everything below writes that leading interpreter and script path as `borgee-agen
 
 On `task get`, `task update`, `task set-property` and `task delete-property` the task id is an optional leading positional. Inside a task thread, omitting it addresses this thread's own task: the host's published binding names it, and where the host published none the gateway scans the parent channel's visible tasks for this thread instead — so pass the id explicitly when that scan cannot land on a single task. `task list` and `task create` are refused inside a task thread; they belong to the parent channel. In a parent channel every one of those ids is required, and omitting it answers `not_found`.
 
-The keys `task set-property` and `task delete-property` accept are a closed set, and a value has a size limit: see `references/task-properties.md`.
+The keys `task set-property` and `task delete-property` accept are a closed set, and a value has a size limit: see `references/task-properties.md`. In this slice, `workspace.mode` still records the host-managed scratch isolation hint, while `execution.local_directory` is a human-owned execution target that hosted agents may read but must not retarget through the generic task-property rail.
 
 ## What is available on a turn
 
-`health`, `bootstrap`, `whoami`, `history` and the task commands are live on every turn whose prompt names a gateway credential file.
+`health`, `bootstrap`, `whoami`, `history`, `users` and the task commands are live on every turn whose prompt names a gateway credential file.
 
-`users`, `draft`, `send` and `mention` are live only where collaboration is enabled; the prompt says when it is not, and the gateway answers `not_found` for all four. `draft`, `send` and `mention` additionally need the turn execution id the prompt carries: no command returns that id and the gateway credential file does not hold it.
+`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.
 
-A `not_found` from `draft` therefore has two readings — collaboration is off, or the host holds no draft for this turn yet — so take it as an answer about the draft, not as evidence that `users`, `send` and `mention` have gone.
+A `not_found` from `draft` therefore has two readings — collaboration is off, or the host holds no draft for this turn yet — so take it as an answer about the draft, not as evidence that `users`, `send` and `mention` have all gone.
 
 Whether you are in a parent channel or inside a task assignment thread is in the prompt too, and it decides which task grammar above applies.
 

package/skills/borgee-agent/references/errors.md

@@ -22,8 +22,8 @@
 | 429 `collaboration_target_cooldown` | The same reply target or mention set was addressed moments ago. | Do not repeat it. |
 | 404 `not_found` on `task get` / `task update` / a property command with no task id | You are not inside a task thread, so there is no current task to resolve. | Pass the task id. |
 | 404 `not_found` on a task command with a task id | The task does not exist, or belongs to another channel. | Check the id with `task list`. |
-| 404 `not_found` on `users`, `send`, `mention` | Collaboration is not enabled for this turn, so those commands do not exist. | Do not use them; the turn prompt says when they are live. |
-| 404 `not_found` on `draft` | Either collaboration is not enabled for this turn, or the host holds no draft for it yet — a draft exists only once the turn has produced visible reply text. | Not a verdict on the other collaboration commands: `users`, `send` and `mention` may well answer on this same turn. Carry on and read the draft later if you still need it. |
+| 404 `not_found` on `send`, `mention` | Collaboration is not enabled for this turn, so those commands do not exist. | Do not use them; the turn prompt says when they are live. |
+| 404 `not_found` on `draft` | Either collaboration is not enabled for this turn, or the host holds no draft for it yet — a draft exists only once the turn has produced visible reply text. | Not a verdict on the other collaboration commands: `users` may still answer on this same turn, and `send` / `mention` may answer once collaboration is live. Carry on and read the draft later if you still need it. |
 | 404 `bootstrap_unavailable` | The host has not published this turn's channel payload yet. | Retry the read once; if it persists, continue without it. |
 | 400 `task_thread_collection_not_allowed` | `task list` or `task create` inside a task thread. | Those belong to the parent channel. |
 | 400 `multiline_message_body_not_allowed`, `message_body_too_verbose` | An auxiliary send must be one line of at most 12 words, and the `<@id>` the CLI appends counts as one of them — each extra `--mention` costs another. | Shorten it to a single-line notice. |

package/skills/borgee-agent/references/task-properties.md

@@ -1,12 +1,14 @@
 # Task properties
 
-A task property associates a task with something that lives outside it. Use one to record what a reader would otherwise have to hunt for in the thread — the pull request that implements the task, the issue it came from.
+A task property associates a task with something that lives outside it, or with a closed task-level runtime choice. Use one to record what a reader would otherwise have to hunt for in the thread — the pull request that implements the task, the issue it came from, or the execution metadata a human attached to it.
 
 Read them back with `task get`: every task response carries a `properties` object, `{}` when the task has none.
 
 ```
 borgee-agent --gateway <path> task set-property <task-id> --key link.pr --value https://github.com/org/repo/pull/12
 borgee-agent --gateway <path> task delete-property <task-id> --key link.pr
+borgee-agent --gateway <path> task set-property <task-id> --key workspace.mode --value isolated
+borgee-agent --gateway <path> task delete-property <task-id> --key workspace.mode
 ```
 
 The task id is omitted only inside that task's own thread, where the request resolves to the thread's task.
@@ -19,6 +21,8 @@ The key set is closed; writing an unregistered key is rejected with `unknown_pro
 | --- | --- |
 | `link.pr` | The pull request that implements this task. Set it as soon as the PR exists, not at the end. |
 | `link.issue` | The issue or ticket the task originates from. |
+| `execution.local_directory` | The explicit local directory a human selected as this task thread's execution target. New tasks default it from the immediately previous task thread in the same channel: if that previous task carried a value, the new task inherits it; if the previous task left it unset, the new task also starts unset. Hosted agents can read it, but the generic agent task-property rail must not write it. Humans set it through the existing user rail. The extra single-human-user guard applies when a task thread is about to switch into somebody's own local workspace/project directory, not as a blanket rule on every property write. A separate agents-host local policy switch governs whether a hosted agent may enter an independent workspace for a task thread that originated from another agent's task. |
+| `workspace.mode` | The host-managed scratch-workspace isolation hint for task threads. `inherit` keeps the scratch workspace on the shared host-managed path, while `isolated` reserves the task's own host-managed scratch workspace shape. Deleting the key returns to the default `inherit` behavior. |
 | `agent.session_id` | Do not write this. It is registered, so a write is accepted and lands — overwriting the host's record of which provider session worked this task. The host writes it itself after each turn. |
 
 ## One key per call
@@ -27,4 +31,4 @@ Each call writes exactly one key, and that is what makes it safe to write a prop
 
 ## Value
 
-A value is a plain string of at most 8 KiB; a longer one is rejected with `property_value_too_long`. It is a reference — a URL, an identifier — never a document.
+A value is a plain string of at most 8 KiB; a longer one is rejected with `property_value_too_long`. It is a reference — a URL, an identifier — never a document. `execution.local_directory` must be a non-empty absolute path string. Before a human lets a task thread switch into their own local workspace/project directory, first verify that the task's parent channel has exactly one human user; otherwise keep the thread discussion-only. If a hosted agent is trying to enter an independent workspace for a task thread that originated from another agent's task, this agents-host's local handoff policy must also allow it. Some registered keys are closed enums: `workspace.mode` accepts only `inherit` or `isolated`.

package/dist/durable-cursor-store.d.ts

@@ -1,5 +0,0 @@
-import { type CursorStore } from './plugin-sdk.js';
-export interface DurableCursorStoreOptions {
-    stateRootDir: string;
-}
-export declare function createDurableCursorStore(options: DurableCursorStoreOptions): CursorStore;

package/dist/durable-cursor-store.js

@@ -1,7 +0,0 @@
-import { FileCursorStore } from './plugin-sdk.js';
-import { resolveAgentCursorPath } from './state-paths.js';
-export function createDurableCursorStore(options) {
-    return new FileCursorStore({
-        resolvePath: (agentId) => resolveAgentCursorPath(options.stateRootDir, agentId),
-    });
-}