@squidcloud/backend 1.0.489 → 1.0.490

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (39) hide show
  1. package/dist/backend/src/internal/source-code.d.ts +0 -2
  2. package/dist/backend/src/source-code/index.d.ts +1 -17
  3. package/dist/backend/src/source-code/source-provider-adapter.d.ts +9 -2
  4. package/dist/backend/src/source-code/trusted-executable.d.ts +3 -0
  5. package/dist/backend/src/workspace-client.d.ts +4 -3
  6. package/dist/cjs/index.js +1 -1
  7. package/dist/cjs/internal/source-code.js +1 -1
  8. package/dist/esm/index.js +1 -1
  9. package/dist/esm/internal/source-code.js +1 -1
  10. package/dist/internal-common/src/public-types-backend/ai-agent.public-context.d.ts +22 -0
  11. package/package.json +2 -2
  12. package/dist/backend/src/cli-agent/claude-code.adapter.d.ts +0 -79
  13. package/dist/backend/src/cli-agent/cli-agent-adapter.types.d.ts +0 -134
  14. package/dist/backend/src/cli-agent/cli-agent-process-launcher.d.ts +0 -22
  15. package/dist/backend/src/cli-agent/cli-agent-process-runner.d.ts +0 -35
  16. package/dist/backend/src/cli-agent/cli-agent-root-status.d.ts +0 -25
  17. package/dist/backend/src/cli-agent/cli-agent-status.utils.d.ts +0 -9
  18. package/dist/backend/src/cli-agent/cli-output-stream.utils.d.ts +0 -1
  19. package/dist/backend/src/cli-agent/codex.adapter.d.ts +0 -82
  20. package/dist/backend/src/cli-agent/index.d.ts +0 -10
  21. package/dist/backend/src/cli-agent/nsjail-source-process-launcher.d.ts +0 -43
  22. package/dist/backend/src/cli-agent/workspace.utils.d.ts +0 -20
  23. package/dist/backend/src/source-code/local-source-development-runner.d.ts +0 -10
  24. package/dist/backend/src/source-code/restricted-source-runner.d.ts +0 -87
  25. package/dist/backend/src/source-code/source-code-analyzer.d.ts +0 -58
  26. package/dist/backend/src/source-code/source-code-errors.d.ts +0 -13
  27. package/dist/backend/src/source-code/source-code-limits.d.ts +0 -23
  28. package/dist/backend/src/source-code/source-code-telemetry.d.ts +0 -31
  29. package/dist/backend/src/source-code/source-development-runtime.d.ts +0 -2
  30. package/dist/backend/src/source-code/source-egress-proxy.d.ts +0 -123
  31. package/dist/backend/src/source-code/source-evidence-verifier.d.ts +0 -110
  32. package/dist/backend/src/source-code/source-model-proxy.constants.d.ts +0 -6
  33. package/dist/backend/src/source-code/source-provider-operation-broker.d.ts +0 -111
  34. package/dist/backend/src/source-code/source-repository-snapshot.d.ts +0 -15
  35. package/dist/backend/src/source-code/source-socket-admission.d.ts +0 -17
  36. package/dist/backend/src/source-code/source-submodule-url.d.ts +0 -10
  37. package/dist/backend/src/source-code/source-workspace-manager.d.ts +0 -162
  38. package/dist/backend/src/source-code/source-workspace-manifest.d.ts +0 -43
  39. package/dist/backend/src/source-code/windows-local-cli-process-launcher.d.ts +0 -13
@@ -1,6 +1,7 @@
1
1
  import { AiConnectedIntegrationMetadata, AiSessionContext, AllAiAgentChatOptions } from '@squidcloud/client';
2
2
  import { AiFunctionId } from '@squidcloud/client';
3
3
  import { AiAgentId, IntegrationId } from '@squidcloud/client';
4
+ import { AuthWithBearer } from '@squidcloud/client';
4
5
  import { IntegrationType } from '@squidcloud/client';
5
6
  /**
6
7
  * Context object passed as a second parameter to every AI function call,
@@ -43,6 +44,27 @@ export declare class SecureAiAgentContext {
43
44
  readonly agentId: AiAgentId;
44
45
  readonly options?: AllAiAgentChatOptions;
45
46
  }
47
+ /**
48
+ * Provides context to a knowledge base's `accessControl.scopeResolver` function, which turns the caller
49
+ * into the set of access scopes they hold for one knowledge base search.
50
+ *
51
+ * The caller is taken from the authenticated request, never from anything the client can shape, so a
52
+ * client cannot ask for another user's scopes. `auth` is `undefined` for an unauthenticated caller and
53
+ * for one authenticating with an API key rather than a user token — in both cases the search sees only
54
+ * content stamped public, so returning an empty array is the correct answer for a caller you cannot
55
+ * identify.
56
+ *
57
+ * @category AI
58
+ */
59
+ export interface ResolveKbScopesContext {
60
+ /** The knowledge base being searched. */
61
+ knowledgeBaseId: string;
62
+ /**
63
+ * The authenticated caller, carrying their `userId` and JWT `attributes`. The same object
64
+ * `this.squid.getUserAuth()` returns inside the function.
65
+ */
66
+ auth: AuthWithBearer | undefined;
67
+ }
46
68
  /**
47
69
  * A type defining an AI functions configurator request.
48
70
  * @category AI
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@squidcloud/backend",
3
- "version": "1.0.489",
3
+ "version": "1.0.490",
4
4
  "description": "Squid Cloud's backend SDK",
5
5
  "main": "dist/cjs/index.js",
6
6
  "module": "dist/esm/index.js",
@@ -57,7 +57,7 @@
57
57
  "typedoc-plugin-markdown": "^4.8.1"
58
58
  },
59
59
  "peerDependencies": {
60
- "@squidcloud/client": "^1.0.489"
60
+ "@squidcloud/client": "^1.0.490"
61
61
  },
62
62
  "engines": {
63
63
  "node": ">=20.0.0"
@@ -1,79 +0,0 @@
1
- import { Readable } from 'stream';
2
- import { AgentCliSessionAdapter, CliAgentAdapterDeps, CliRunOutcome, SessionCtx } from './cli-agent-adapter.types';
3
- /** Mongo doc cap (~16 MB) with headroom for BSON envelope + lock subdoc. */
4
- export declare const CLAUDE_BLOB_MAX_BYTES: number;
5
- /**
6
- * Claude Code adapter. All Claude-specific knowledge (CLI flags, stream-json
7
- * parsing, MCP wiring, security guardrails) lives here. The manager only sees
8
- * the generic `AgentCliSessionAdapter` surface.
9
- *
10
- * Lifecycle per run:
11
- * 1. Manager prepares tmp sandboxHome and unpacks prior blob.
12
- * 2. Manager calls `buildArgs(ctx, sessionExists)` which:
13
- * a. creates an MCP session (if tools configured)
14
- * b. writes MCP config + system prompt files into sandboxHome
15
- * c. returns the full CLI argv
16
- * 3. Manager spawns claude, pipes prompt to stdin, hands streams to parseOutput.
17
- * 4. parseOutput consumes stream-json and resolves to CliRunOutcome.
18
- * 5. Manager either persists (.claude subtree) or releases the lock.
19
- * 6. afterRun deletes the MCP session.
20
- */
21
- export declare class ClaudeCodeCliAdapter implements AgentCliSessionAdapter {
22
- private readonly deps;
23
- readonly providerKey = "claude-code";
24
- readonly displayName = "Claude Code";
25
- readonly cliBinary = "claude";
26
- /**
27
- * Self-kill deadline for the CLI, resolved from the caller's `quotas.maxRuntimeSeconds` (default:
28
- * the platform maximum). Core always runs CLI-agent asks as long-running jobs, so no transport
29
- * deadline applies; this bound only guards against a hung or runaway CLI spending Anthropic tokens
30
- * indefinitely.
31
- */
32
- readonly maxWallTimeMs: number;
33
- readonly maxBlobBytes: number;
34
- /** Stored between buildArgs and afterRun so we can clean up the MCP session. */
35
- private mcpSessionId;
36
- /** Tracks the root status while the process lifecycle is active. */
37
- private readonly rootStatus;
38
- /** Creates a Claude adapter for one request. */
39
- constructor(deps: CliAgentAdapterDeps);
40
- /**
41
- * Memory ids come from the customer (or default to clientId). Claude CLI's
42
- * `--session-id`/`--resume` require a valid UUID v4, so we deterministically
43
- * hash whatever we got. Already-valid UUIDs pass through lowercased so the
44
- * file path stays stable between materialisations.
45
- */
46
- deriveSessionId(memoryId: string): string;
47
- /**
48
- * Claude CLI hashes the absolute cwd into a "project slug" used for
49
- * `.claude/projects/<slug>/<sid>.jsonl`. For `--resume` to find the persisted
50
- * transcript, that slug — and therefore the absolute cwd — must be byte-for-byte
51
- * identical on every turn. The manager's sandboxHome is a fresh random tmp dir
52
- * per request, so we deliberately root the cwd OUTSIDE it, in a stable location
53
- * keyed only by sessionKey. Persisted state still lives under the sandbox
54
- * (CLAUDE_CONFIG_DIR); this directory is just scratch and is cleaned in afterRun.
55
- */
56
- cwd(ctx: SessionCtx): string;
57
- /** Builds the Claude-specific process environment. */
58
- buildEnv(ctx: SessionCtx): Record<string, string>;
59
- /** Builds fixed Claude CLI arguments and optional MCP configuration. */
60
- buildArgs(ctx: SessionCtx, sessionExists: boolean): Promise<string[]>;
61
- /**
62
- * Persist the entire `.claude` subtree. That includes `projects/<slug>/<sid>.jsonl`
63
- * (the actual transcript) plus any CLI-managed metadata we might rely on for resume.
64
- */
65
- statePaths(_ctx: SessionCtx): string[];
66
- /** Parses Claude stream-json output into a terminal response. */
67
- parseOutput(stdout: Readable, stderr: Readable, prompt: string): Promise<CliRunOutcome>;
68
- /** Publishes the terminal replacement selected by the process lifecycle. */
69
- completeRun(outcome: CliRunOutcome): void;
70
- /** Deletes temporary MCP and working-directory state. */
71
- afterRun(ctx: SessionCtx): Promise<void>;
72
- /**
73
- * Windows spawns Claude through shell:true (npm-global .cmd shim), so paths
74
- * passed on argv need quoting and forward-slashes. POSIX hands argv to execvp
75
- * directly, so quoting would be interpreted literally — return the bare path.
76
- */
77
- private cliPath;
78
- private cliEmptyArgument;
79
- }
@@ -1,134 +0,0 @@
1
- import { AiConnectedIntegrationMetadata, AiConnectedKnowledgeBaseMetadata, AiFunctionIdWithContext, UserAiAskResponse, UserAiChatOptions } from '@squidcloud/client';
2
- import { Readable } from 'node:stream';
3
- /** Contains the per-request paths and identifiers used by a CLI adapter. */
4
- export interface SessionCtx {
5
- /** Identifies persisted state for one agent and memory. */
6
- sessionKey: string;
7
- /** Identifies the provider CLI session. */
8
- sessionId: string;
9
- /** Points to the isolated per-run home directory. */
10
- sandboxHome: string;
11
- /** Identifies the owning Squid application. */
12
- appId: string;
13
- /** Identifies the calling Squid agent. */
14
- agentId: string;
15
- /** Identifies the selected conversation memory. */
16
- memoryId: string;
17
- /** Identifies a shared workspace when one is configured. */
18
- workspaceId?: string;
19
- }
20
- /** Describes the terminal result of one CLI process run. */
21
- export type CliRunOutcome = {
22
- kind: 'success';
23
- response: UserAiAskResponse;
24
- } | {
25
- kind: 'cli-error';
26
- response: UserAiAskResponse;
27
- } | {
28
- kind: 'error';
29
- error: Error;
30
- } | {
31
- kind: 'timeout';
32
- };
33
- /** Configures the Squid tools exposed to a CLI adapter. */
34
- export interface CliToolsConfig {
35
- /** Lists the Squid functions exposed to the CLI. */
36
- functions?: Array<AiFunctionIdWithContext>;
37
- /** Lists the integrations exposed to the CLI. */
38
- connectedIntegrations?: Array<AiConnectedIntegrationMetadata>;
39
- /** Lists the knowledge bases exposed to the CLI. */
40
- connectedKnowledgeBases?: Array<AiConnectedKnowledgeBaseMetadata>;
41
- }
42
- /** Contains the result returned when Core creates an agent-tools session. */
43
- export interface CreateAgentToolsSessionResponse {
44
- /** Identifies the temporary tools session. */
45
- sessionId: string;
46
- /** Authenticates calls to the temporary tools session. */
47
- sessionToken: string;
48
- /** Locates the session-specific MCP endpoint. */
49
- mcpUrl: string;
50
- }
51
- /** Describes one observable CLI activity update. */
52
- export interface CliAgentStatusUpdate {
53
- /** Identifies an update so later events can replace it in place. */
54
- messageId?: string;
55
- /** Supplies the short activity label. */
56
- title: string;
57
- /** Supplies Markdown-formatted activity details. */
58
- body: string;
59
- /** Nests this activity beneath another status update. */
60
- parentStatusUpdateId?: string;
61
- /** Supplies optional machine-readable activity metadata. */
62
- tags?: Record<string, unknown>;
63
- }
64
- /** Supplies per-request services and settings to a CLI adapter. */
65
- export interface CliAgentAdapterDeps {
66
- /** Contains the model and per-request AI options. */
67
- options: UserAiChatOptions;
68
- /** Supplies the credential exposed to the selected CLI process. */
69
- apiKey: string;
70
- /** Supplies explicitly authorized secret environment variables. */
71
- secretsAsEnv: Record<string, string>;
72
- /** Describes the Squid tools available to this run. */
73
- toolsConfig: CliToolsConfig;
74
- /** Indicates whether the adapter should configure MCP tools. */
75
- hasTools: boolean;
76
- /** Locates the trusted Squid backend used for MCP sessions. */
77
- backendBaseUrl: string;
78
- /** Supplies the trusted system prompt appended to the CLI request. */
79
- systemPrompt: string;
80
- /**
81
- * Controls whether the adapter writes Codex auth.json on the host filesystem.
82
- * Restricted source runs delegate that write to the isolated rootfs entrypoint.
83
- */
84
- writeCodexAuthFile?: boolean;
85
- /** Enables the fixed no-memory, no-inherited-instructions source-analyzer argument set. */
86
- restrictedMode?: boolean;
87
- /** Overrides the immutable Claude settings path for an explicitly local restricted run. */
88
- restrictedSettingsPath?: string;
89
- /** Overrides the tools exposed to Claude inside an explicitly restricted run. */
90
- restrictedTools?: string;
91
- /** Constrains Claude's terminal response to one validated JSON value. */
92
- structuredOutputSchema?: Record<string, unknown>;
93
- /** Routes restricted Codex through the source model proxy by default; set to false for direct local development. */
94
- useSourceModelProxy?: boolean;
95
- /** Uses the CLI's read-only host sandbox when no outer source-agent jail is available locally. */
96
- useHostReadOnlySandbox?: boolean;
97
- /** Emits literal Windows arguments for a launcher that does not interpolate through cmd.exe. */
98
- useLiteralWindowsArguments?: boolean;
99
- /** Creates a temporary MCP session for the run. */
100
- createMcpSession(): Promise<CreateAgentToolsSessionResponse>;
101
- /** Deletes a temporary MCP session after the run. */
102
- deleteMcpSession(sessionId: string): Promise<void>;
103
- /** Publishes an observable activity update for the run. */
104
- publishStatus?(update: CliAgentStatusUpdate): void;
105
- }
106
- /** Describes one supported CLI without owning its process lifecycle. */
107
- export interface AgentCliSessionAdapter {
108
- /** Identifies the adapter's AI provider. */
109
- readonly providerKey: string;
110
- /** Supplies the provider name shown to users. */
111
- readonly displayName: string;
112
- /** Names the executable launched for this adapter. */
113
- readonly cliBinary: string;
114
- /** Bounds the process wall-clock duration. */
115
- readonly maxWallTimeMs: number;
116
- /** Bounds persisted provider session state. */
117
- readonly maxBlobBytes: number;
118
- /** Derives the provider-compatible session identifier. */
119
- deriveSessionId(memoryId: string): string;
120
- /** Resolves the process working directory. */
121
- cwd(ctx: SessionCtx): string;
122
- /** Builds the adapter-specific environment. */
123
- buildEnv(ctx: SessionCtx): Record<string, string>;
124
- /** Builds the adapter-specific command arguments. */
125
- buildArgs(ctx: SessionCtx, sessionExists: boolean): Promise<string[]> | string[];
126
- /** Lists provider state paths eligible for persistence. */
127
- statePaths(ctx: SessionCtx): string[];
128
- /** Parses bounded process streams into a terminal outcome. */
129
- parseOutput(stdout: Readable, stderr: Readable, prompt: string): Promise<CliRunOutcome>;
130
- /** Publishes the terminal run status after the process lifecycle selects its final outcome. */
131
- completeRun(outcome: CliRunOutcome): void;
132
- /** Releases provider-specific resources after the process exits. */
133
- afterRun?(ctx: SessionCtx): Promise<void>;
134
- }
@@ -1,22 +0,0 @@
1
- import { ChildProcess } from 'node:child_process';
2
- /** Describes one process launch without exposing shell interpolation. */
3
- export interface CliAgentLaunchRequest {
4
- /** Names the executable to launch. */
5
- binary: string;
6
- /** Contains literal command arguments. */
7
- args: string[];
8
- /** Selects the process working directory. */
9
- cwd: string;
10
- /** Supplies the complete process environment. */
11
- environment: NodeJS.ProcessEnv;
12
- }
13
- /** Launches a CLI process using an injectable isolation boundary. */
14
- export interface CliAgentProcessLauncher {
15
- /** Launches one process with piped standard streams. */
16
- launch(request: CliAgentLaunchRequest): Promise<ChildProcess>;
17
- }
18
- /** Launches ordinary CLI sessions directly on the tenant host. */
19
- export declare class HostCliProcessLauncher implements CliAgentProcessLauncher {
20
- /** Launches the requested CLI with piped standard streams. */
21
- launch(request: CliAgentLaunchRequest): Promise<ChildProcess>;
22
- }
@@ -1,35 +0,0 @@
1
- import { AgentCliSessionAdapter, CliRunOutcome, SessionCtx } from './cli-agent-adapter.types';
2
- import { CliAgentProcessLauncher } from './cli-agent-process-launcher';
3
- /** Re-exports launcher contracts used by process-runner callers. */
4
- export type { CliAgentLaunchRequest, CliAgentProcessLauncher } from './cli-agent-process-launcher';
5
- /** Configures one CLI process run. */
6
- export interface CliAgentProcessRunOptions {
7
- /** Supplies the explicit base environment for the process. */
8
- baseEnvironment: NodeJS.ProcessEnv;
9
- /** Aborts the process tree when triggered. */
10
- signal?: AbortSignal;
11
- /** Overrides the default host process launcher. */
12
- launcher?: CliAgentProcessLauncher;
13
- /** Lists values that must never reach parsed output or logs. */
14
- sensitiveValues?: readonly string[];
15
- }
16
- /** Configures output byte ceilings for CLI processes. */
17
- export interface CliAgentProcessLimits {
18
- /** Bounds raw stdout bytes. */
19
- maxStdoutBytes: number;
20
- /** Bounds combined stdout and stderr bytes. */
21
- maxOutputBytes: number;
22
- }
23
- /** Owns CLI spawning, bounded output, timeout, abort, and process-tree cleanup. */
24
- export declare class CliAgentProcessRunner {
25
- private readonly limits;
26
- /** Creates a process runner with validated output ceilings. */
27
- constructor(limits?: CliAgentProcessLimits);
28
- /** Runs one CLI adapter through the selected launcher. */
29
- run(adapter: AgentCliSessionAdapter, prompt: string, context: SessionCtx, sessionExists: boolean, options: CliAgentProcessRunOptions): Promise<CliRunOutcome>;
30
- private runChild;
31
- private ensureProcessExited;
32
- private waitForTreeDead;
33
- private isProcessTreeAlive;
34
- private killTree;
35
- }
@@ -1,25 +0,0 @@
1
- import { CliAgentStatusUpdate, CliRunOutcome } from './cli-agent-adapter.types';
2
- /** Configures the root status shared by CLI-agent adapters. */
3
- export interface CliAgentRootStatusOptions {
4
- /** Supplies the provider name shown to users. */
5
- displayName: string;
6
- /** Formats provider-specific errors for display. */
7
- formatError(error: string): string;
8
- /** Supplies the run bound for timeout status text. */
9
- maxWallTimeMs(): number;
10
- /** Publishes status updates when the caller requested them. */
11
- publishStatus?(update: CliAgentStatusUpdate): void;
12
- }
13
- /** Owns one CLI run's root status lifecycle and accumulated token usage. */
14
- export declare class CliAgentRootStatus {
15
- private readonly options;
16
- private active;
17
- /** Creates a root-status lifecycle for one adapter instance. */
18
- constructor(options: CliAgentRootStatusOptions);
19
- /** Starts tracking the root status published by the adapter parser. */
20
- begin(messageId: string): void;
21
- /** Records the latest cumulative token usage for the terminal replacement. */
22
- recordUsage(inputTokens: number, outputTokens: number): void;
23
- /** Publishes one terminal replacement after the process runner selects its final outcome. */
24
- complete(outcome: CliRunOutcome): void;
25
- }
@@ -1,9 +0,0 @@
1
- /** Contains compact user-visible details for one CLI tool invocation. */
2
- export interface CompactToolActivity {
3
- /** Supplies the Markdown body shown when the tool invocation is expanded. */
4
- body: string;
5
- /** Supplies the single-line description shown in a collapsed tool group. */
6
- summary: string;
7
- }
8
- /** Formats common CLI tool arguments without exposing tool output or internal workspace prefixes. */
9
- export declare function formatCompactToolActivity(toolName: string, input: Record<string, unknown> | undefined): CompactToolActivity;
@@ -1,82 +0,0 @@
1
- import { Readable } from 'stream';
2
- import { AgentCliSessionAdapter, CliAgentAdapterDeps, CliRunOutcome, SessionCtx } from './cli-agent-adapter.types';
3
- /** Mongo doc cap (~16 MB) with headroom for BSON envelope + lock subdoc. */
4
- export declare const CODEX_BLOB_MAX_BYTES: number;
5
- /**
6
- * Codex adapter. All Codex-specific knowledge (CLI flags, JSONL event parsing, thread-id capture,
7
- * state layout) lives here. The manager only sees the generic `AgentCliSessionAdapter` surface.
8
- *
9
- * Session model (verified on codex-cli 0.137.0): Codex generates its own session id and emits it as
10
- * the first `thread.started` event. There is no flag to force an id on `exec`, so on the first turn
11
- * we capture that id into a sidecar file inside $CODEX_HOME (persisted with the session blob) and on
12
- * the next turn resume with `codex exec resume <id>`.
13
- *
14
- * Tools/MCP: when `hasTools` is set, the adapter opens a core agent-tools session and registers it
15
- * as a streamable-HTTP MCP server via `-c mcp_servers.*` overrides (Codex authenticates it with a
16
- * bearer token read from `MCP_BEARER_ENV_VAR`). The session is torn down in `afterRun`.
17
- */
18
- export declare class CodexCliAdapter implements AgentCliSessionAdapter {
19
- private readonly deps;
20
- readonly providerKey = "codex";
21
- readonly displayName = "Codex";
22
- readonly cliBinary = "codex";
23
- /**
24
- * Self-kill deadline for the CLI, resolved from the caller's `quotas.maxRuntimeSeconds` (default:
25
- * the platform maximum). Core always runs CLI-agent asks as long-running jobs, so no transport
26
- * deadline applies; this bound only guards against a hung or runaway CLI spending OpenAI tokens
27
- * indefinitely.
28
- */
29
- readonly maxWallTimeMs: number;
30
- readonly maxBlobBytes: number;
31
- /** Absolute path of the thread-id sidecar; set in buildArgs, written in parseOutput. */
32
- private threadIdFilePath;
33
- /** Absolute path Codex writes its final message to (-o); set in buildArgs, read in parseOutput. */
34
- private lastMessageFilePath;
35
- /** Per-run agent-tools MCP session id; set in buildArgs (when hasTools), deleted in afterRun. */
36
- private mcpSessionId;
37
- /** Per-run MCP bearer token; captured in buildArgs, exposed to the CLI via buildEnv. */
38
- private mcpBearerToken;
39
- /** Tracks the root status while the process lifecycle is active. */
40
- private readonly rootStatus;
41
- /** Creates a Codex adapter for one request. */
42
- constructor(deps: CliAgentAdapterDeps);
43
- /**
44
- * Codex never receives this id (it generates its own thread id), but the manager still needs a
45
- * stable value in SessionCtx for logging/`none`-mode isolation. Derive a deterministic UUID from
46
- * the memoryId, mirroring the Claude adapter.
47
- */
48
- deriveSessionId(memoryId: string): string;
49
- /** Resolves the stable working directory for this session. */
50
- cwd(ctx: SessionCtx): string;
51
- /** Builds the Codex-specific process environment. */
52
- buildEnv(ctx: SessionCtx): Record<string, string>;
53
- /** Builds fixed Codex CLI arguments and optional MCP configuration. */
54
- buildArgs(ctx: SessionCtx, sessionExists: boolean): Promise<string[]>;
55
- /**
56
- * Persist only what `resume` needs: the `sessions/` rollout plus our thread-id sidecar (verified on
57
- * codex-cli 0.137.0 — restoring just these two recalls prior context). Deliberately EXCLUDES
58
- * `auth.json` (holds the API key), the SQLite app DBs, and the bundled `skills/` tree, keeping the
59
- * blob small and free of secrets.
60
- */
61
- statePaths(_ctx: SessionCtx): string[];
62
- /** Parses Codex JSONL output into a terminal response. */
63
- parseOutput(stdout: Readable, stderr: Readable, prompt: string): Promise<CliRunOutcome>;
64
- /** Publishes the terminal replacement selected by the process lifecycle. */
65
- completeRun(outcome: CliRunOutcome): void;
66
- /** Deletes temporary MCP and working-directory state. */
67
- afterRun(ctx: SessionCtx): Promise<void>;
68
- /**
69
- * Whether this run's sandbox home is a host directory this adapter may write into, which is what
70
- * separates a session from a restricted source run: the latter's home materialises inside the jail,
71
- * so it delegates every file it needs — the auth file included — to the rootfs entrypoint.
72
- */
73
- private get ownsSandboxHome();
74
- /**
75
- * Whether this run gets the session temporary directory of {@link TMPDIR_REL}. A restricted run is
76
- * excluded on both counts named there: it brings its own, and only a host-owned home can hold one.
77
- */
78
- private get ownsSessionTmpDir();
79
- /** Writes the captured thread id into the sidecar so it round-trips with the session blob. */
80
- private persistThreadId;
81
- private readPersistedThreadId;
82
- }
@@ -1,10 +0,0 @@
1
- export * from './claude-code.adapter';
2
- export * from './cli-agent-adapter.types';
3
- export * from './cli-agent-process-launcher';
4
- export * from './cli-agent-process-runner';
5
- export * from './cli-agent-root-status';
6
- export * from './cli-agent-status.utils';
7
- export * from './cli-output-stream.utils';
8
- export * from './codex.adapter';
9
- export * from './nsjail-source-process-launcher';
10
- export * from './workspace.utils';
@@ -1,43 +0,0 @@
1
- import { ChildProcess } from 'node:child_process';
2
- import { type Stats } from 'node:fs';
3
- import { CliAgentLaunchRequest, CliAgentProcessLauncher } from './cli-agent-process-launcher';
4
- /** Configures the immutable nsjail boundary for one source-analysis run. */
5
- export interface NsjailSourceProcessLauncherConfig {
6
- /** Points to the outer per-run directory that owns the broker sockets. */
7
- runtimeDirectory?: string;
8
- /** Points to the disposable workspace-local source tree. */
9
- workspaceDirectory: string;
10
- /** Points to the trusted model proxy socket. */
11
- modelSocket: string;
12
- /** Points to the trusted provider broker socket. */
13
- providerSocket: string;
14
- /** Bounds wall-clock and CPU time for the jail. */
15
- timeoutMs: number;
16
- /** Selects the outer tenant user mapped to UID 65532. */
17
- tenantUid?: number;
18
- /** Selects the outer tenant group mapped to GID 65532. */
19
- tenantGid?: number;
20
- /** Points to the immutable analyzer root filesystem. */
21
- rootfs?: string;
22
- /** Points to the trusted nsjail seccomp policy. */
23
- seccompPolicy?: string;
24
- /** Selects the entrypoint inside the immutable rootfs. */
25
- entrypoint?: string;
26
- /** Overrides the nsjail executable for deployment or testing. */
27
- nsjailBinary?: string;
28
- }
29
- /** Launches a source analyzer inside the fail-closed source-agent nsjail. */
30
- export declare class NsjailSourceProcessLauncher implements CliAgentProcessLauncher {
31
- private readonly config;
32
- private readonly rootfs;
33
- private readonly seccompPolicy;
34
- private readonly entrypoint;
35
- /** Creates a launcher for one disposable workspace and pair of broker sockets. */
36
- constructor(config: NsjailSourceProcessLauncherConfig);
37
- /** Launches nsjail after verifying every required production boundary. */
38
- launch(request: CliAgentLaunchRequest): Promise<ChildProcess>;
39
- /** Builds nsjail arguments without embedding environment values or credentials. */
40
- buildArguments(request: CliAgentLaunchRequest): string[];
41
- }
42
- /** Returns whether a security-boundary executable is a root-owned regular file unavailable for tenant writes. */
43
- export declare function isTrustedBoundaryExecutable(statistics: Pick<Stats, 'gid' | 'isFile' | 'mode' | 'uid'>): boolean;
@@ -1,20 +0,0 @@
1
- import { SessionCtx } from './cli-agent-adapter.types';
2
- /**
3
- * Resolves the absolute working directory for a workspace, or null when no id was given. The directory
4
- * lives on this pod's local disk; `AgentCliSessionManager` keeps it in sync with the shared workspace
5
- * server (via `WorkspaceClient.create`/`push`) around each run, not a network-mounted volume. Throws
6
- * on a malformed id so a caller bug surfaces instead of silently falling back to a scratch dir.
7
- */
8
- export declare function resolveWorkspaceCwd(workspaceId: string | undefined): string | null;
9
- /**
10
- * The cwd a CLI adapter should spawn into: the workspace directory when `ctx.workspaceId` is set,
11
- * otherwise a deterministic per-session scratch directory under `ephemeralRoot` (a provider-specific
12
- * namespace, e.g. so Claude Code and Codex scratch dirs never collide).
13
- */
14
- export declare function resolveCwd(ctx: SessionCtx, ephemeralRoot: string): string;
15
- /**
16
- * Deletes `cwd` unless it's a workspace directory — a workspace persists across asks (and providers), so
17
- * it must never be wiped here; only the ephemeral scratch cwd is the adapter's to clean; the same
18
- * deterministic scratch path is recreated next turn.
19
- */
20
- export declare function cleanupEphemeralCwd(ctx: SessionCtx, cwd: string, logPrefix: string): Promise<void>;
@@ -1,10 +0,0 @@
1
- import type { RestrictedSourceRunRequest, RestrictedSourceRunResult, SourceCodeRuntimeOptions } from './restricted-source-runner';
2
- /** Runs a restricted source analyzer directly on an explicitly local Windows tenant. */
3
- export declare class LocalSourceDevelopmentRunner {
4
- private readonly processRunner;
5
- private readonly runtimeOptions;
6
- /** Creates the local runner with the production output and timeout ceilings. */
7
- constructor(runtimeOptions?: SourceCodeRuntimeOptions);
8
- /** Runs one analyzer with isolated local configuration and removes all per-run state. */
9
- run(request: RestrictedSourceRunRequest): Promise<RestrictedSourceRunResult>;
10
- }
@@ -1,87 +0,0 @@
1
- import { CanonicalReasoningEffort, SourceCodeAnalyzerModel, SourceControlProvider } from '@squidcloud/client';
2
- import { CliAgentStatusUpdate } from '../cli-agent/cli-agent-adapter.types';
3
- import { CliAgentProcessLauncher } from '../cli-agent/cli-agent-process-launcher';
4
- import { CliAgentProcessRunner } from '../cli-agent/cli-agent-process-runner';
5
- import { NsjailSourceProcessLauncherConfig } from '../cli-agent/nsjail-source-process-launcher';
6
- import { SourceProviderOperationBroker } from './source-provider-operation-broker';
7
- /** Configures the resource ceilings and immutable rootfs for source analysis. */
8
- export interface SourceCodeRuntimeOptions {
9
- /** Bounds writable workspace bytes. */
10
- maxWorkspaceBytes: number;
11
- /** Bounds writable workspace inodes. */
12
- maxRunInodes: number;
13
- /** Bounds raw analyzer stdout bytes. */
14
- maxStdoutBytes: number;
15
- /** Bounds combined analyzer stdout and stderr bytes. */
16
- maxOutputBytes: number;
17
- /** Bounds analyzer wall-clock duration. */
18
- analyzerTimeoutMs: number;
19
- /** Points to the immutable source-agent rootfs. */
20
- rootfs: string;
21
- }
22
- /** Supplies the production defaults used when deployment configuration is absent. */
23
- export declare const DEFAULT_SOURCE_CODE_RUNTIME_OPTIONS: Readonly<SourceCodeRuntimeOptions>;
24
- /** Describes one restricted source-analysis request. */
25
- export interface RestrictedSourceRunRequest {
26
- /** Selects the source-control provider. */
27
- provider: SourceControlProvider;
28
- /** Selects the isolated CLI analyzer. */
29
- analyzerModel: SourceCodeAnalyzerModel;
30
- /** Selects a concrete model from the analyzer provider's CLI registry. */
31
- analyzerModelId?: string;
32
- /** Selects the reasoning effort used by the analyzer CLI. */
33
- analyzerReasoningEffort?: CanonicalReasoningEffort;
34
- /** Supplies the real model credential to the outer proxy only. */
35
- analyzerApiKey: string;
36
- /** Supplies the credential-owning provider broker. */
37
- providerBroker: SourceProviderOperationBroker;
38
- /** Contains the source-analysis question and trusted instructions. */
39
- prompt: string;
40
- /** Points to the disposable prepared source tree. */
41
- analyzerRootDirectory: string;
42
- /** Requests a timeout no greater than the deployment ceiling. */
43
- timeoutMs: number;
44
- /** Publishes observable analyzer activity to the calling AI session. */
45
- publishStatus?: (update: CliAgentStatusUpdate) => void;
46
- }
47
- /** Contains the user-visible response and model usage for one restricted run. */
48
- export interface RestrictedSourceRunResult {
49
- /** Contains the analyzer's bounded text response. */
50
- response: string;
51
- /** Reports model input token usage. */
52
- inputTokens: number;
53
- /** Reports model output token usage. */
54
- outputTokens: number;
55
- }
56
- /** Represents the lifecycle needed from a model-auth proxy. */
57
- export interface SourceModelAuthProxyLike {
58
- /** Starts the proxy on a private Unix socket. */
59
- start(socketPath: string): Promise<void>;
60
- /** Stops the proxy and releases its socket. */
61
- close(): Promise<void>;
62
- }
63
- /** Supplies testable boundaries to the restricted runner. */
64
- export interface RestrictedSourceRunnerDependencies {
65
- /** Runs the bounded CLI process. */
66
- processRunner: CliAgentProcessRunner;
67
- /** Selects the host directory for private per-run sockets. */
68
- runtimeRootDirectory: string;
69
- /** Creates the credential-owning model proxy. */
70
- createModelProxy(request: {
71
- analyzerModel: SourceCodeAnalyzerModel;
72
- apiKey: string;
73
- }): SourceModelAuthProxyLike;
74
- /** Creates the isolated process launcher. */
75
- createLauncher(config: NsjailSourceProcessLauncherConfig): CliAgentProcessLauncher;
76
- }
77
- /** Runs a source analyzer with credentials and ambient tenant state outside its jail. */
78
- export declare class RestrictedSourceRunner {
79
- private readonly dependencies;
80
- private readonly runtimeOptions;
81
- /** Creates a production runner unless explicit test boundaries are supplied. */
82
- constructor(dependencies?: RestrictedSourceRunnerDependencies, runtimeOptions?: SourceCodeRuntimeOptions);
83
- /** Runs one analyzer and removes every per-run resource on all exits. */
84
- run(request: RestrictedSourceRunRequest): Promise<RestrictedSourceRunResult>;
85
- }
86
- /** Validates and snapshots deployment-provided runtime settings. */
87
- export declare function validateSourceCodeRuntimeOptions(options: SourceCodeRuntimeOptions): SourceCodeRuntimeOptions;