@capekai/core 1.0.3 → 1.0.5

package/README.md

@@ -10,3 +10,46 @@ Requires Bun 1.3 or newer.
 npm install @capekai/core
 ```
 Public subpaths include `composition`, `plugins`, `hosts`, `execution`, `providers`, `tools`, `ask-authority`, `sandbox`, `workspace`, `configuration`, `tool`, and `storage`.
+
+## Workspace policy
+
+Čapek owns path resolution and containment. Embedding hosts can supply their own blocked paths, sensitive patterns, and home directory when composing an agent:
+
+```ts
+import { createComposition } from '@capekai/core/composition';
+
+const composition = await createComposition(processScope, {
+  ...values,
+  workspacePolicy: {
+    blockedPaths: ['/proc/', '/sys/'],
+    sensitivePatterns: ['.env', '.pem', '.key'],
+    homeDir: '/home/agent',
+  },
+});
+```
+
+Hosts building a custom plugin profile can configure the same policy directly:
+
+```ts
+import { workspacePolicyPlugin } from '@capekai/core/plugins';
+
+workspacePolicyPlugin('host.workspace-policy', {
+  blockedPaths: [],
+  sensitivePatterns: ['credentials'],
+  homeDir: '/srv/agent',
+});
+```
+
+For workspace helpers used outside an agent scope, configure the process-wide policy during host bootstrap:
+
+```ts
+import { configureWorkspacePolicy } from '@capekai/core/workspace';
+
+configureWorkspacePolicy({
+  blockedPaths: ['/proc/', '/sys/'],
+  sensitivePatterns: ['.env', '.pem', '.key'],
+  homeDir: '/home/agent',
+});
+```
+
+Call `configureWorkspacePolicy()` with no argument, or omit composition options, to retain the compatibility defaults.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@capekai/core",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "description": "Bun-native composable agent runtime and framework for Capek.",
   "license": "MIT",
   "repository": {
@@ -77,8 +77,8 @@
   "dependencies": {
     "@ai-sdk/deepseek": "^2.0.35",
     "@ai-sdk/openai": "^3.0.84",
-    "@capekai/tool": "^1.0.2",
-    "@capekai/types": "^1.0.1",
+    "@capekai/tool": "^1.0.3",
+    "@capekai/types": "^1.0.2",
     "@openrouter/ai-sdk-provider": "^2.3.3",
     "@zip.js/zip.js": "^2.7.60",
     "ai": "^6.0.116",

package/src/core/message-utils.ts

@@ -4,6 +4,7 @@ import { isTextPart, isToolPart, isImagePart, isFilePart, parseToolInput } from
 import { stripVisualization } from '../utils/strip-visualization';
 import { getAttachment } from '../storage/runtime';
 import { isToolOutputArtifactReference, RETRIEVE_TOOL_OUTPUT_NAME } from '../tool-output/policy';
+import { toolModelOutputToAiSdk } from '../tools/model-output';
 
 type AiSdkContent = string | Array<{
   type: 'text' | 'tool-call' | 'tool-result' | 'image' | 'file';
@@ -121,7 +122,9 @@ export async function convertToAiSdkMessages(
               type: 'tool-result' as const,
               toolCallId: toolPart.callId,
               toolName: toolPart.name,
-              output: { type: 'json' as const, value: stripVisualization(toolPart.state.output) },
+              output: toolPart.state.modelOutput
+                ? toolModelOutputToAiSdk(toolPart.state.modelOutput)
+                : { type: 'json' as const, value: stripVisualization(toolPart.state.output) },
             });
           }
         } else if (toolPart.state.status === 'error') {

package/src/core/stream-handlers.ts

@@ -2,6 +2,7 @@ import type { TextPart, ToolPart, ReasoningPart, MessageEvent } from '@capekai/t
 import { createPart, updatePart, getPart, persistStreamingPartSnapshots } from '../storage/runtime';
 import { parseToolInput } from './part-utils';
 import { randomUUID } from 'crypto';
+import { isCapekToolOutputEnvelope } from '../tools/model-output';
 
 const STREAM_PART_PERSIST_INTERVAL_MS = 300;
 
@@ -184,8 +185,11 @@ export function createStreamHandlers(ctx: StreamHandlerContext) {
         const latestPart = await getPart(existingToolPart.id) as ToolPart | null;
         const latestState = latestPart?.state;
 
+        const capekOutput = isCapekToolOutputEnvelope(delta.output) ? delta.output : undefined;
         let resultData: unknown;
-        if (typeof delta.output === 'string') {
+        if (capekOutput) {
+          resultData = capekOutput.value;
+        } else if (typeof delta.output === 'string') {
           try {
             resultData = JSON.parse(delta.output);
           } catch {
@@ -218,6 +222,7 @@ export function createStreamHandlers(ctx: StreamHandlerContext) {
                 status: 'completed' as const,
                 input: existingToolPart.state.input,
                 output: resultData,
+                ...(capekOutput && { modelOutput: capekOutput.modelOutput }),
                 startedAt: Date.now(),
                 completedAt: Date.now(),
                 ...(existingChildSessionId && { childSessionId: existingChildSessionId }),

package/src/core/tool-builders/external-tools.ts

@@ -20,6 +20,10 @@ import {
 import { isToolAllowedInContext, type ToolExecutionScope } from '../tool-capabilities';
 import type { ToolMap } from './types';
 import type { BroadcastFn } from '../../runtime/host-dependencies';
+import {
+  capekToolOutputToAiSdk,
+  createCapekToolOutputEnvelope,
+} from '../../tools/model-output';
 
 export interface ExternalToolsOptions {
   toolNames: string[];
@@ -88,6 +92,7 @@ export async function buildExternalTools(options: ExternalToolsOptions): Promise
     tools[name] = tool({
       description: definition.description,
       inputSchema: jsonSchema(definition.inputSchema),
+      toModelOutput: ({ output }) => capekToolOutputToAiSdk(output),
       execute: async (args: Record<string, unknown>, { toolCallId }: { toolCallId: string }) => {
         const toolAbortController = interruptManager.registerToolExecution(sessionId, toolCallId);
 
@@ -121,11 +126,10 @@ export async function buildExternalTools(options: ExternalToolsOptions): Promise
             return { error: result.error ?? 'Tool execution failed' };
           }
 
-          if (result.visualization && result.result && typeof result.result === 'object') {
-            return { ...result.result as Record<string, unknown>, _visualization: result.visualization };
-          }
-
-          return result.result;
+          const clientResult = result.visualization && result.result && typeof result.result === 'object'
+            ? { ...result.result as Record<string, unknown>, _visualization: result.visualization }
+            : result.result;
+          return createCapekToolOutputEnvelope(clientResult, result.modelOutput);
         } finally {
           interruptManager.unregisterToolExecution(sessionId, toolCallId);
           await rejectPendingAsksByToolCallId(toolCallId);

package/src/internal/workspace.ts

@@ -9,6 +9,7 @@
  */
 
 export {
+  configureWorkspacePolicy,
   expandPath,
   isInsideUnselectedAdditionalRoot,
   isPathInside,

package/src/plugins/facade-plugins.ts

@@ -16,6 +16,7 @@ import type { SandboxController } from '../sandbox/controller';
 import type { StorageBundle } from '../storage/contracts';
 import type { ToolRegistryResolver } from '../tools/registry';
 import type { WorkspaceToolDiscovery } from '../tools/tool-source';
+import type { WorkspacePolicyOptions } from '../workspace/contracts';
 import { getSchedulerHost } from '../scheduler/host';
 import { getSessionSearchHost } from '../session-search/host';
 import { createContextSectionsPlugin } from './context-sections';
@@ -64,6 +65,9 @@ export interface FacadeScopeValues {
   host: RuntimeHost;
   contextSources: Partial<ContextSources>;
   workspaceToolDiscovery: WorkspaceToolDiscovery;
+  /** Host-owned path classification values. When omitted, the current
+   * compatibility defaults apply. */
+  workspacePolicy?: WorkspacePolicyOptions;
   /** Optional compatibility resolver. When omitted, the facade
    * composition derives the resolver from the composed scope's effective
    * contributed tool payloads. The explicit value is the rollback
@@ -109,7 +113,7 @@ export function createFacadeAgentPlugins(values: FacadeScopeValues): readonly Ca
     retryPolicyPlugin('facade.retry-policy'),
     compactionPolicyPlugin('facade.compaction-policy'),
     permissionPolicyPlugin('facade.permission-policy'),
-    workspacePolicyPlugin('facade.workspace-policy'),
+    workspacePolicyPlugin('facade.workspace-policy', values.workspacePolicy),
     toolOutputPolicyPlugin('facade.tool-output-policy'),
     contextSourcesValuePlugin('facade.context-sources', values.contextSources),
     // Facade context parity: the facade keeps the legacy self-delegation and

package/src/plugins/workspace-policy.ts

@@ -1,11 +1,6 @@
 import type { CapekPlugin, PluginContext } from '../kernel/types';
-import { homedir } from 'os';
-import { SENSITIVE_FILE_PATTERNS } from '@capekai/types';
-import {
-  BLOCKED_PATHS,
-  createWorkspaceService,
-  type WorkspacePolicyOptions,
-} from '../workspace/policy';
+import type { WorkspacePolicyOptions } from '../workspace/contracts';
+import { createWorkspaceService } from '../workspace/policy';
 import { capekWorkspacePolicyKey } from './service-keys';
 
 /**
@@ -17,17 +12,15 @@ import { capekWorkspacePolicyKey } from './service-keys';
  * current containment, root classification, expansion, and sensitive/blocked
  * denial behavior.
  */
-export function workspacePolicyPlugin(id: string): CapekPlugin<unknown> {
+export function workspacePolicyPlugin(
+  id: string,
+  options?: WorkspacePolicyOptions,
+): CapekPlugin<unknown> {
   return {
     id,
     scope: 'agent',
     provides: [capekWorkspacePolicyKey],
     setup(context: PluginContext) {
-      const options: WorkspacePolicyOptions = {
-        blockedPaths: [...BLOCKED_PATHS],
-        sensitivePatterns: [...SENSITIVE_FILE_PATTERNS],
-        homeDir: homedir(),
-      };
       context.provide(
         capekWorkspacePolicyKey,
         createWorkspaceService({ id, options }),

package/src/tool-output/policy.ts

@@ -34,6 +34,10 @@ import type {
   ToolOutputPolicyContext,
   ToolOutputPolicyOptions,
 } from './contracts';
+import {
+  isCapekToolOutputEnvelope,
+  type CapekToolOutputEnvelope,
+} from '../tools/model-output';
 
 export const TOOL_OUTPUT_THRESHOLD_CHARS = 50_000;
 export const TOOL_OUTPUT_PREVIEW_CHARS = 10_000;
@@ -116,6 +120,13 @@ export function createToolOutputService(
   const outputPolicyWrappedTools = new WeakSet<object>();
 
   async function applyToolOutputPolicy(result: unknown, context: ToolOutputPolicyContext): Promise<unknown> {
+    if (isCapekToolOutputEnvelope(result)) {
+      return {
+        ...result,
+        value: await applyToolOutputPolicy(result.value, context),
+      } satisfies CapekToolOutputEnvelope;
+    }
+
     const visualization = result && typeof result === 'object' && !Array.isArray(result)
       ? (result as Record<string, unknown>)._visualization
       : undefined;

package/src/tools/model-output.ts

@@ -0,0 +1,75 @@
+import type { JSONValue, Tool } from 'ai';
+import type { ToolModelOutputPart } from '@capekai/types';
+
+type AiSdkToolResultOutput = Awaited<ReturnType<NonNullable<Tool['toModelOutput']>>>;
+
+const CAPEK_TOOL_OUTPUT_TYPE = 'capek-tool-output';
+
+export interface CapekToolOutputEnvelope {
+  type: typeof CAPEK_TOOL_OUTPUT_TYPE;
+  value: unknown;
+  modelOutput: ToolModelOutputPart[];
+}
+
+function isToolModelOutputPart(value: unknown): value is ToolModelOutputPart {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return false;
+  const part = value as Record<string, unknown>;
+  if (part.type === 'text') {
+    return typeof part.text === 'string';
+  }
+  if (part.type === 'image') {
+    return typeof part.data === 'string'
+      && part.data.length > 0
+      && !part.data.startsWith('data:')
+      && typeof part.mediaType === 'string'
+      && part.mediaType.startsWith('image/');
+  }
+  return false;
+}
+
+export function normalizeToolModelOutput(value: unknown): ToolModelOutputPart[] | undefined {
+  if (!Array.isArray(value) || value.length === 0 || !value.every(isToolModelOutputPart)) {
+    return undefined;
+  }
+  return value;
+}
+
+export function createCapekToolOutputEnvelope(
+  value: unknown,
+  modelOutput: unknown,
+): unknown {
+  const normalized = normalizeToolModelOutput(modelOutput);
+  return normalized
+    ? { type: CAPEK_TOOL_OUTPUT_TYPE, value, modelOutput: normalized }
+    : value;
+}
+
+export function isCapekToolOutputEnvelope(value: unknown): value is CapekToolOutputEnvelope {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return false;
+  const record = value as Record<string, unknown>;
+  return record.type === CAPEK_TOOL_OUTPUT_TYPE
+    && 'value' in record
+    && normalizeToolModelOutput(record.modelOutput) !== undefined;
+}
+
+export function toolModelOutputToAiSdk(parts: ToolModelOutputPart[]): AiSdkToolResultOutput {
+  return {
+    type: 'content',
+    value: parts.map((part) => part.type === 'text'
+      ? { type: 'text' as const, text: part.text }
+      : {
+          type: 'image-data' as const,
+          data: part.data,
+          mediaType: part.mediaType,
+        }),
+  };
+}
+
+export function capekToolOutputToAiSdk(output: unknown): AiSdkToolResultOutput {
+  if (isCapekToolOutputEnvelope(output)) {
+    return toolModelOutputToAiSdk(output.modelOutput);
+  }
+  return typeof output === 'string'
+    ? { type: 'text', value: output }
+    : { type: 'json', value: (output ?? null) as JSONValue };
+}

package/src/workspace/policy.ts

@@ -47,6 +47,14 @@ function defaultOptions(): WorkspacePolicyOptions {
   };
 }
 
+function freezeOptions(options: WorkspacePolicyOptions): Readonly<WorkspacePolicyOptions> {
+  return Object.freeze({
+    blockedPaths: Object.freeze([...options.blockedPaths]),
+    sensitivePatterns: Object.freeze([...options.sensitivePatterns]),
+    homeDir: options.homeDir,
+  });
+}
+
 // ── Mandatory containment runtime (C6 step 6) ───────────────────────────
 // The tool-runtime capability is constructed HERE, not by provider methods:
 // a custom provider supplies only frozen options (blocked paths, sensitive
@@ -130,7 +138,7 @@ export function createWorkspaceService(
   createOptions: WorkspaceServiceCreateOptions = {},
 ): WorkspaceService {
   const id = createOptions.id ?? 'workspace.default';
-  const options = createOptions.options ?? defaultOptions();
+  const options = freezeOptions(createOptions.options ?? defaultOptions());
 
   const service: WorkspaceService = {
     id,
@@ -251,6 +259,15 @@ export function getWorkspaceService(): WorkspaceService {
     ?? (processDefaultService ??= createWorkspaceService({ id: 'workspace.process-default' }));
 }
 
+/** Configures the process-wide policy used outside an agent scope. Omitting
+ * options restores the compatibility defaults. */
+export function configureWorkspacePolicy(options?: WorkspacePolicyOptions): void {
+  processDefaultService = createWorkspaceService({
+    id: 'workspace.process-default',
+    options,
+  });
+}
+
 /** Builds the tool-runtime capability over the active workspace policy. */
 export function createWorkspaceCapability(host: WorkspaceCapabilityHost): WorkspaceCapability {
   return createWorkspaceCapabilityWithOptions(host, getWorkspaceService().options);