@tealbrick/kit 0.3.0-rc.1 → 0.3.0-rc.10

package/dist/native-claude.d.ts

@@ -0,0 +1,99 @@
+import type { AccessMode, HarnessAdapter } from '@tealbrick/portal/native-bridge';
+import { type ClaudeAttachment, type ClaudeProfile } from './native-serve-config.js';
+import { type GrantUsageStore } from './native-standing-grants.js';
+/** Minimal structural view of @anthropic-ai/claude-agent-sdk (validated against 0.3.287). */
+export interface ClaudeQuery extends AsyncIterable<any> {
+    interrupt?(): Promise<unknown>;
+    close?(): void;
+    accountInfo?(): Promise<any>;
+}
+export interface ClaudeSdk {
+    query(params: {
+        prompt: AsyncIterable<any>;
+        options: Record<string, any>;
+    }): ClaudeQuery;
+    getSessionInfo?(sessionId: string, options?: {
+        dir?: string;
+    }): Promise<unknown>;
+    /** In-process MCP servers (SDK `createSdkMcpServer` / `tool`). */
+    createSdkMcpServer?(options: {
+        name: string;
+        version?: string;
+        tools?: unknown[];
+    }): unknown;
+    tool?(name: string, description: string, inputSchema: Record<string, unknown>, handler: (args: any, extra: unknown) => Promise<any>): unknown;
+}
+export declare function loadClaudeSdk(root: string, sdkModule?: string): Promise<ClaudeSdk>;
+/** `sandbox`: the owner's sandboxed workspace session (Restricted mode when `claude.workspace` is configured). */
+export type ClaudeAccess = {
+    mode: AccessMode;
+    revision: number;
+    tools: string[];
+    sandbox?: boolean;
+};
+/** Built-in tools Restricted mode exposes: read-only and contained to the workspace. */
+export declare const readOnlyTools: string[];
+export declare const workspaceTools: string[];
+/** Claude Code's per-cwd temp folder name: every non-alphanumeric character becomes '-'. */
+export declare const claudeTmpSlug: (dir: string) => string;
+/** Claude Code's sandbox temp roots for this OS user (sandboxed Bash TMPDIR), shared by every session of the user. */
+export declare const claudeTmpRoots: (uid: number) => string[];
+/** In-process (unsandboxed) filesystem tools: never available in the sandboxed workspace session, owner or expert. */
+export declare const unsandboxedFileTools: string[];
+/** Homebrew prefixes the sandboxed shell keeps reading (only those present are listed). Never the whole /opt/homebrew. */
+export declare const homebrewReadRoots: string[];
+/** Removed from the model's context unless a wider access mode explicitly lists them. */
+export declare const restrictedDenied: string[];
+/** Chat-relay identity secrets: never forwarded to the SDK process, even if listed in envPassthrough. */
+export declare const neverForwardedEnv: string[];
+/** WebFetch targets the workspace session may not reach: non-http(s), loopback/private/link-local/CGNAT IPs and local names. */
+export declare function privateWebTarget(raw: unknown): string | undefined;
+/** What a Portal registration id refers to; resolved from the runtime's own capability snapshot. */
+export type AppRef = {
+    appId: string;
+    plugin?: string;
+    action?: string;
+};
+export interface ToolPolicy {
+    access: ClaudeAccess;
+    profile: ClaudeProfile;
+    protectedPaths: string[];
+    resolveApp?: (registrationId: string) => Promise<AppRef | undefined>;
+    /** Exact in-process MCP tool names for the owner session only (never expert subagents), without payload approval. */
+    ownerTools?: string[];
+}
+/** Contract experts that may reach the owner's Teal Brick connector (still bounded per call by decideTool). */
+export declare const contractsWithAppAccess: (profile: ClaudeProfile) => string[];
+/** Payload-bound approval: owner-wide approval operations, plus a contract's own list and any outward write by a contract expert. */
+export declare function needsApproval(profile: ClaudeProfile, name: string, input: Record<string, unknown>, agentType?: string): boolean;
+/** Single decision point for PreToolUse hooks and canUseTool. Names and decisions only are logged. */
+export declare function decideTool(policy: ToolPolicy, name: string, input: Record<string, unknown>, agentId?: string, agentType?: string): Promise<{
+    allow: boolean;
+    reason: string;
+}>;
+export interface ClaudeHarnessOptions {
+    name: string;
+    profile: ClaudeProfile;
+    attachment: ClaudeAttachment;
+    sdk: ClaudeSdk;
+    protectedPaths: string[];
+    log?: (event: Record<string, unknown>) => void;
+    env?: NodeJS.ProcessEnv;
+    /** Resolves registration ids to apps for contract scope checks. */
+    resolveApp?: (registrationId: string) => Promise<AppRef | undefined>;
+    /** Owner-only directory for per-run delegation trace records (JSONL). */
+    traceDir?: string;
+    /** How long a payload approval may wait before it is denied. */
+    approvalTimeoutMs?: number;
+    /** Owner-session in-process MCP servers, created per turn (an SDK server instance serves one query). */
+    extraMcpServers?: (sessionId: string) => Record<string, unknown>;
+    /** Exact `mcp__<server>__<tool>` names from extraMcpServers allowed for the owner session only. */
+    extraTools?: string[];
+    /** Appended to the owner session's system prompt. */
+    systemNote?: string;
+    /** Usage counters for claude.standingGrants (shared by native serve and acp); in-memory when omitted. */
+    standingGrants?: GrantUsageStore;
+}
+/** Claude Agent SDK adapter. Claude's persisted session transcript is the source of truth;
+ * every turn is a fresh query() that resumes the same session id. */
+export declare function claudeHarness(options: ClaudeHarnessOptions): HarnessAdapter<ClaudeAccess>;