@squidcloud/backend 1.0.483 → 1.0.485

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 (43) hide show
  1. package/dist/backend/src/cli-agent/claude-code.adapter.d.ts +75 -0
  2. package/dist/backend/src/cli-agent/cli-agent-adapter.types.d.ts +122 -0
  3. package/dist/backend/src/cli-agent/cli-agent-process-launcher.d.ts +22 -0
  4. package/dist/backend/src/cli-agent/cli-agent-process-runner.d.ts +35 -0
  5. package/dist/backend/src/cli-agent/codex.adapter.d.ts +67 -0
  6. package/dist/backend/src/cli-agent/index.d.ts +7 -0
  7. package/dist/backend/src/cli-agent/nsjail-source-process-launcher.d.ts +43 -0
  8. package/dist/backend/src/cli-agent/workspace.utils.d.ts +20 -0
  9. package/dist/backend/src/internal/source-code.d.ts +3 -0
  10. package/dist/backend/src/public-types.d.ts +4 -0
  11. package/dist/backend/src/source-code/index.d.ts +22 -0
  12. package/dist/backend/src/source-code/local-source-development-runner.d.ts +10 -0
  13. package/dist/backend/src/source-code/providers/bitbucket-cloud.client.d.ts +20 -0
  14. package/dist/backend/src/source-code/providers/github-app.client.d.ts +45 -0
  15. package/dist/backend/src/source-code/providers/index.d.ts +2 -0
  16. package/dist/backend/src/source-code/restricted-source-runner.d.ts +86 -0
  17. package/dist/backend/src/source-code/source-analysis-admission-controller.d.ts +35 -0
  18. package/dist/backend/src/source-code/source-code-analyzer.d.ts +60 -0
  19. package/dist/backend/src/source-code/source-code-errors.d.ts +13 -0
  20. package/dist/backend/src/source-code/source-code-limits.d.ts +33 -0
  21. package/dist/backend/src/source-code/source-code-telemetry.d.ts +35 -0
  22. package/dist/backend/src/source-code/source-development-runtime.d.ts +2 -0
  23. package/dist/backend/src/source-code/source-egress-proxy.d.ts +123 -0
  24. package/dist/backend/src/source-code/source-evidence-verifier.d.ts +30 -0
  25. package/dist/backend/src/source-code/source-git-command.d.ts +82 -0
  26. package/dist/backend/src/source-code/source-git-credential-helper.d.ts +5 -0
  27. package/dist/backend/src/source-code/source-model-proxy.constants.d.ts +6 -0
  28. package/dist/backend/src/source-code/source-provider-adapter.d.ts +87 -0
  29. package/dist/backend/src/source-code/source-provider-operation-broker.d.ts +111 -0
  30. package/dist/backend/src/source-code/source-repository-snapshot.d.ts +15 -0
  31. package/dist/backend/src/source-code/source-socket-admission.d.ts +17 -0
  32. package/dist/backend/src/source-code/source-submodule-url.d.ts +10 -0
  33. package/dist/backend/src/source-code/source-workspace-manager.d.ts +169 -0
  34. package/dist/backend/src/source-code/source-workspace-manifest.d.ts +43 -0
  35. package/dist/backend/src/source-code/windows-local-cli-process-launcher.d.ts +13 -0
  36. package/dist/backend/src/squid.service.d.ts +16 -0
  37. package/dist/backend/src/workspace-client.d.ts +104 -2
  38. package/dist/cjs/index.js +1 -1
  39. package/dist/cjs/internal/source-code.js +1 -0
  40. package/dist/esm/index.js +1 -1
  41. package/dist/esm/internal/source-code.js +1 -0
  42. package/dist/internal-common/src/public-types-backend/bundle-data.public-types.d.ts +1 -1
  43. package/package.json +24 -2
@@ -0,0 +1,75 @@
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
+ /** Creates a Claude adapter for one request. */
37
+ constructor(deps: CliAgentAdapterDeps);
38
+ /**
39
+ * Memory ids come from the customer (or default to clientId). Claude CLI's
40
+ * `--session-id`/`--resume` require a valid UUID v4, so we deterministically
41
+ * hash whatever we got. Already-valid UUIDs pass through lowercased so the
42
+ * file path stays stable between materialisations.
43
+ */
44
+ deriveSessionId(memoryId: string): string;
45
+ /**
46
+ * Claude CLI hashes the absolute cwd into a "project slug" used for
47
+ * `.claude/projects/<slug>/<sid>.jsonl`. For `--resume` to find the persisted
48
+ * transcript, that slug — and therefore the absolute cwd — must be byte-for-byte
49
+ * identical on every turn. The manager's sandboxHome is a fresh random tmp dir
50
+ * per request, so we deliberately root the cwd OUTSIDE it, in a stable location
51
+ * keyed only by sessionKey. Persisted state still lives under the sandbox
52
+ * (CLAUDE_CONFIG_DIR); this directory is just scratch and is cleaned in afterRun.
53
+ */
54
+ cwd(ctx: SessionCtx): string;
55
+ /** Builds the Claude-specific process environment. */
56
+ buildEnv(ctx: SessionCtx): Record<string, string>;
57
+ /** Builds fixed Claude CLI arguments and optional MCP configuration. */
58
+ buildArgs(ctx: SessionCtx, sessionExists: boolean): Promise<string[]>;
59
+ /**
60
+ * Persist the entire `.claude` subtree. That includes `projects/<slug>/<sid>.jsonl`
61
+ * (the actual transcript) plus any CLI-managed metadata we might rely on for resume.
62
+ */
63
+ statePaths(_ctx: SessionCtx): string[];
64
+ /** Parses Claude stream-json output into a terminal response. */
65
+ parseOutput(stdout: Readable, stderr: Readable, prompt: string): Promise<CliRunOutcome>;
66
+ /** Deletes temporary MCP and working-directory state. */
67
+ afterRun(ctx: SessionCtx): Promise<void>;
68
+ /**
69
+ * Windows spawns Claude through shell:true (npm-global .cmd shim), so paths
70
+ * passed on argv need quoting and forward-slashes. POSIX hands argv to execvp
71
+ * directly, so quoting would be interpreted literally — return the bare path.
72
+ */
73
+ private cliPath;
74
+ private cliEmptyArgument;
75
+ }
@@ -0,0 +1,122 @@
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
+ /** Supplies per-request services and settings to a CLI adapter. */
52
+ export interface CliAgentAdapterDeps {
53
+ /** Contains the model and per-request AI options. */
54
+ options: UserAiChatOptions;
55
+ /** Supplies the credential exposed to the selected CLI process. */
56
+ apiKey: string;
57
+ /** Supplies explicitly authorized secret environment variables. */
58
+ secretsAsEnv: Record<string, string>;
59
+ /** Describes the Squid tools available to this run. */
60
+ toolsConfig: CliToolsConfig;
61
+ /** Indicates whether the adapter should configure MCP tools. */
62
+ hasTools: boolean;
63
+ /** Locates the trusted Squid backend used for MCP sessions. */
64
+ backendBaseUrl: string;
65
+ /** Supplies the trusted system prompt appended to the CLI request. */
66
+ systemPrompt: string;
67
+ /**
68
+ * Controls whether the adapter writes Codex auth.json on the host filesystem.
69
+ * Restricted source runs delegate that write to the isolated rootfs entrypoint.
70
+ */
71
+ writeCodexAuthFile?: boolean;
72
+ /** Enables the fixed no-memory, no-inherited-instructions source-analyzer argument set. */
73
+ restrictedMode?: boolean;
74
+ /** Overrides the immutable Claude settings path for an explicitly local restricted run. */
75
+ restrictedSettingsPath?: string;
76
+ /** Overrides the tools exposed to Claude inside an explicitly restricted run. */
77
+ restrictedTools?: string;
78
+ /** Routes restricted Codex through the source model proxy by default; set to false for direct local development. */
79
+ useSourceModelProxy?: boolean;
80
+ /** Uses the CLI's read-only host sandbox when no outer source-agent jail is available locally. */
81
+ useHostReadOnlySandbox?: boolean;
82
+ /** Emits literal Windows arguments for a launcher that does not interpolate through cmd.exe. */
83
+ useLiteralWindowsArguments?: boolean;
84
+ /** Creates a temporary MCP session for the run. */
85
+ createMcpSession(): Promise<CreateAgentToolsSessionResponse>;
86
+ /** Deletes a temporary MCP session after the run. */
87
+ deleteMcpSession(sessionId: string): Promise<void>;
88
+ /** Publishes a bounded progress update for the run. */
89
+ publishStatus?(update: {
90
+ title: string;
91
+ body: string;
92
+ parentStatusUpdateId?: string;
93
+ tags?: Record<string, unknown>;
94
+ }): void;
95
+ }
96
+ /** Describes one supported CLI without owning its process lifecycle. */
97
+ export interface AgentCliSessionAdapter {
98
+ /** Identifies the adapter's AI provider. */
99
+ readonly providerKey: string;
100
+ /** Supplies the provider name shown to users. */
101
+ readonly displayName: string;
102
+ /** Names the executable launched for this adapter. */
103
+ readonly cliBinary: string;
104
+ /** Bounds the process wall-clock duration. */
105
+ readonly maxWallTimeMs: number;
106
+ /** Bounds persisted provider session state. */
107
+ readonly maxBlobBytes: number;
108
+ /** Derives the provider-compatible session identifier. */
109
+ deriveSessionId(memoryId: string): string;
110
+ /** Resolves the process working directory. */
111
+ cwd(ctx: SessionCtx): string;
112
+ /** Builds the adapter-specific environment. */
113
+ buildEnv(ctx: SessionCtx): Record<string, string>;
114
+ /** Builds the adapter-specific command arguments. */
115
+ buildArgs(ctx: SessionCtx, sessionExists: boolean): Promise<string[]> | string[];
116
+ /** Lists provider state paths eligible for persistence. */
117
+ statePaths(ctx: SessionCtx): string[];
118
+ /** Parses bounded process streams into a terminal outcome. */
119
+ parseOutput(stdout: Readable, stderr: Readable, prompt: string): Promise<CliRunOutcome>;
120
+ /** Releases provider-specific resources after the process exits. */
121
+ afterRun?(ctx: SessionCtx): Promise<void>;
122
+ }
@@ -0,0 +1,22 @@
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
+ }
@@ -0,0 +1,35 @@
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
+ }
@@ -0,0 +1,67 @@
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
+ /** Creates a Codex adapter for one request. */
40
+ constructor(deps: CliAgentAdapterDeps);
41
+ /**
42
+ * Codex never receives this id (it generates its own thread id), but the manager still needs a
43
+ * stable value in SessionCtx for logging/`none`-mode isolation. Derive a deterministic UUID from
44
+ * the memoryId, mirroring the Claude adapter.
45
+ */
46
+ deriveSessionId(memoryId: string): string;
47
+ /** Resolves the stable working directory for this session. */
48
+ cwd(ctx: SessionCtx): string;
49
+ /** Builds the Codex-specific process environment. */
50
+ buildEnv(ctx: SessionCtx): Record<string, string>;
51
+ /** Builds fixed Codex CLI arguments and optional MCP configuration. */
52
+ buildArgs(ctx: SessionCtx, sessionExists: boolean): Promise<string[]>;
53
+ /**
54
+ * Persist only what `resume` needs: the `sessions/` rollout plus our thread-id sidecar (verified on
55
+ * codex-cli 0.137.0 — restoring just these two recalls prior context). Deliberately EXCLUDES
56
+ * `auth.json` (holds the API key), the SQLite app DBs, and the bundled `skills/` tree, keeping the
57
+ * blob small and free of secrets.
58
+ */
59
+ statePaths(_ctx: SessionCtx): string[];
60
+ /** Parses Codex JSONL output into a terminal response. */
61
+ parseOutput(stdout: Readable, stderr: Readable, prompt: string): Promise<CliRunOutcome>;
62
+ /** Deletes temporary MCP and working-directory state. */
63
+ afterRun(ctx: SessionCtx): Promise<void>;
64
+ /** Writes the captured thread id into the sidecar so it round-trips with the session blob. */
65
+ private persistThreadId;
66
+ private readPersistedThreadId;
67
+ }
@@ -0,0 +1,7 @@
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 './codex.adapter';
6
+ export * from './nsjail-source-process-launcher';
7
+ export * from './workspace.utils';
@@ -0,0 +1,43 @@
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;
@@ -0,0 +1,20 @@
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>;
@@ -0,0 +1,3 @@
1
+ export * from '../cli-agent';
2
+ export * from '../source-code';
3
+ export * from '../source-code/providers';
@@ -1,3 +1,7 @@
1
+ /** Re-exports source-code values from the client SDK. */
2
+ export { SOURCE_CODE_ANALYZER_MODELS, SOURCE_CODE_ANALYZE_FUNCTION_ID, SOURCE_CODE_INTEGRATION_TYPES, SOURCE_CODE_MAX_REPOSITORIES, SOURCE_CODE_MAX_SUPPLEMENTAL_INSTRUCTIONS_LENGTH, SOURCE_CONTROL_PROVIDERS, normalizeBitbucketRepositorySelection, normalizeGitHubRepositorySelection, } from '@squidcloud/client';
3
+ /** Re-exports source-code types from the client SDK. */
4
+ export type { AiAgentSourceCodeIntegrationOptions, AnalyzeCodeRequest, AnalyzeCodeResult, BitbucketRepositoryConfiguration, DiscoverSourceRepositoriesRequest, DiscoverSourceRepositoriesResponse, GitHubRepositoryConfiguration, SourceCodeAnalyzerModel, SourceCodeIntegrationType, SourceCodeLineRange, SourceCodePathEvidence, SourceCodeRef, SourceCodeRepositoryEvidence, SourceControlProvider, SourceRepository, } from '@squidcloud/client';
1
5
  export * from '../../internal-common/src/public-types-backend/ai-agent.public-context';
2
6
  export * from '../../internal-common/src/public-types-backend/api-call.public-context';
3
7
  export * from '../../internal-common/src/public-types-backend/application.public-types';
@@ -0,0 +1,22 @@
1
+ export * from './local-source-development-runner';
2
+ export * from './providers';
3
+ export * from './restricted-source-runner';
4
+ export * from './source-analysis-admission-controller';
5
+ export * from './source-code-analyzer';
6
+ export * from './source-code-errors';
7
+ export * from './source-code-limits';
8
+ export * from './source-code-telemetry';
9
+ export * from './source-development-runtime';
10
+ export * from './source-egress-proxy';
11
+ export * from './source-evidence-verifier';
12
+ export * from './source-git-command';
13
+ export * from './source-git-credential-helper';
14
+ export * from './source-model-proxy.constants';
15
+ export * from './source-provider-adapter';
16
+ export * from './source-provider-operation-broker';
17
+ export * from './source-repository-snapshot';
18
+ export * from './source-socket-admission';
19
+ export * from './source-submodule-url';
20
+ export * from './source-workspace-manager';
21
+ export * from './source-workspace-manifest';
22
+ export * from './windows-local-cli-process-launcher';
@@ -0,0 +1,10 @@
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
+ }
@@ -0,0 +1,20 @@
1
+ import type { SourceRepository } from '@squidcloud/client';
2
+ /** Authenticates one Bitbucket Cloud user through an API token. */
3
+ export interface BitbucketCloudCredentials {
4
+ /** Stores the Atlassian account email. */
5
+ email: string;
6
+ /** Stores the Bitbucket API token. */
7
+ apiToken: string;
8
+ }
9
+ /** Calls Bitbucket Cloud without exposing credentials to callers. */
10
+ export declare class BitbucketCloudClient {
11
+ private readonly fetchFn;
12
+ private readonly authorization;
13
+ /** Creates a client for one Bitbucket Cloud account. */
14
+ constructor(credentials: BitbucketCloudCredentials, fetchFn?: typeof fetch);
15
+ /** Lists every repository visible in one configured workspace. */
16
+ listRepositories(workspace: string, signal?: AbortSignal): Promise<SourceRepository[]>;
17
+ /** Loads one repository from a configured workspace. */
18
+ getRepository(workspace: string, repositorySlug: string, signal?: AbortSignal): Promise<SourceRepository>;
19
+ private request;
20
+ }
@@ -0,0 +1,45 @@
1
+ import type { SourceRepository } from '@squidcloud/client';
2
+ /** Requests a GitHub App installation token. */
3
+ export interface GitHubInstallationTokenRequest {
4
+ /** Limits the token to selected GitHub repository IDs. */
5
+ repositoryIds?: readonly number[];
6
+ /** Limits the token to selected GitHub permissions. */
7
+ permissions?: Readonly<Record<string, 'read' | 'write'>>;
8
+ }
9
+ /** Represents a GitHub App installation token. */
10
+ export interface GitHubInstallationToken {
11
+ /** Stores the temporary GitHub installation token. */
12
+ token: string;
13
+ /** Stores the token's expiry timestamp. */
14
+ expiresAt: string;
15
+ /** Stores the authoritative permissions returned by GitHub. */
16
+ permissions: Readonly<Record<string, 'read' | 'write'>>;
17
+ /** Stores the authoritative repository IDs returned for a selected token. */
18
+ repositoryIds: readonly number[];
19
+ /** Stores whether GitHub scoped the token to all or selected repositories. */
20
+ repositorySelection: 'all' | 'selected';
21
+ }
22
+ /** Configures one GitHub App installation client. */
23
+ export interface GitHubAppClientConfig {
24
+ /** Identifies the GitHub App. */
25
+ appId: string;
26
+ /** Identifies the GitHub App installation. */
27
+ installationId: string;
28
+ /** Supplies the GitHub App private key. */
29
+ privateKey: string;
30
+ }
31
+ /** Calls GitHub's App API without exposing credentials to callers. */
32
+ export declare class GitHubAppClient {
33
+ private readonly fetchFn;
34
+ private readonly appId;
35
+ private readonly installationId;
36
+ private readonly privateKey;
37
+ private readonly tokenCache;
38
+ /** Creates a client for one GitHub App installation. */
39
+ constructor(config: GitHubAppClientConfig, fetchFn?: typeof fetch);
40
+ /** Creates a scoped installation token. */
41
+ createInstallationToken(request: GitHubInstallationTokenRequest, signal?: AbortSignal): Promise<GitHubInstallationToken>;
42
+ /** Lists the repositories installed for this GitHub App. */
43
+ listInstallationRepositories(signal?: AbortSignal): Promise<SourceRepository[]>;
44
+ private createAppJwt;
45
+ }
@@ -0,0 +1,2 @@
1
+ export * from './bitbucket-cloud.client';
2
+ export * from './github-app.client';
@@ -0,0 +1,86 @@
1
+ import { CanonicalReasoningEffort, SourceCodeAnalyzerModel, SourceControlProvider } from '@squidcloud/client';
2
+ import { CliAgentProcessLauncher } from '../cli-agent/cli-agent-process-launcher';
3
+ import { CliAgentProcessRunner } from '../cli-agent/cli-agent-process-runner';
4
+ import { NsjailSourceProcessLauncherConfig } from '../cli-agent/nsjail-source-process-launcher';
5
+ import { SourceProviderOperationBroker } from './source-provider-operation-broker';
6
+ /** Configures the resource ceilings and immutable rootfs for source analysis. */
7
+ export interface SourceCodeRuntimeOptions {
8
+ /** Bounds writable workspace bytes. */
9
+ maxWorkspaceBytes: number;
10
+ /** Bounds writable workspace inodes. */
11
+ maxRunInodes: number;
12
+ /** Bounds raw analyzer stdout bytes. */
13
+ maxStdoutBytes: number;
14
+ /** Bounds combined analyzer stdout and stderr bytes. */
15
+ maxOutputBytes: number;
16
+ /** Bounds analyzer wall-clock duration. */
17
+ analyzerTimeoutMs: number;
18
+ /** Points to the immutable source-agent rootfs. */
19
+ rootfs: string;
20
+ }
21
+ /** Supplies the production defaults used when deployment configuration is absent. */
22
+ export declare const DEFAULT_SOURCE_CODE_RUNTIME_OPTIONS: Readonly<SourceCodeRuntimeOptions>;
23
+ /** Describes one restricted source-analysis request. */
24
+ export interface RestrictedSourceRunRequest {
25
+ /** Selects the source-control provider. */
26
+ provider: SourceControlProvider;
27
+ /** Selects the isolated CLI analyzer. */
28
+ analyzerModel: SourceCodeAnalyzerModel;
29
+ /** Selects a concrete model from the analyzer provider's CLI registry. */
30
+ analyzerModelId?: string;
31
+ /** Selects the reasoning effort used by the analyzer CLI. */
32
+ analyzerReasoningEffort?: CanonicalReasoningEffort;
33
+ /** Supplies the real model credential to the outer proxy only. */
34
+ analyzerApiKey: string;
35
+ /** Supplies the credential-owning provider broker. */
36
+ providerBroker: SourceProviderOperationBroker;
37
+ /** Contains the source-analysis question and trusted instructions. */
38
+ prompt: string;
39
+ /** Points to the disposable prepared source tree. */
40
+ analyzerRootDirectory: string;
41
+ /** Aborts the analyzer when its lease or caller ends. */
42
+ signal: AbortSignal;
43
+ /** Requests a timeout no greater than the deployment ceiling. */
44
+ timeoutMs: number;
45
+ }
46
+ /** Contains the user-visible response and model usage for one restricted run. */
47
+ export interface RestrictedSourceRunResult {
48
+ /** Contains the analyzer's bounded text response. */
49
+ response: string;
50
+ /** Reports model input token usage. */
51
+ inputTokens: number;
52
+ /** Reports model output token usage. */
53
+ outputTokens: number;
54
+ }
55
+ /** Represents the lifecycle needed from a model-auth proxy. */
56
+ export interface SourceModelAuthProxyLike {
57
+ /** Starts the proxy on a private Unix socket. */
58
+ start(socketPath: string): Promise<void>;
59
+ /** Stops the proxy and releases its socket. */
60
+ close(): Promise<void>;
61
+ }
62
+ /** Supplies testable boundaries to the restricted runner. */
63
+ export interface RestrictedSourceRunnerDependencies {
64
+ /** Runs the bounded CLI process. */
65
+ processRunner: CliAgentProcessRunner;
66
+ /** Selects the host directory for private per-run sockets. */
67
+ runtimeRootDirectory: string;
68
+ /** Creates the credential-owning model proxy. */
69
+ createModelProxy(request: {
70
+ analyzerModel: SourceCodeAnalyzerModel;
71
+ apiKey: string;
72
+ }): SourceModelAuthProxyLike;
73
+ /** Creates the isolated process launcher. */
74
+ createLauncher(config: NsjailSourceProcessLauncherConfig): CliAgentProcessLauncher;
75
+ }
76
+ /** Runs a source analyzer with credentials and ambient tenant state outside its jail. */
77
+ export declare class RestrictedSourceRunner {
78
+ private readonly dependencies;
79
+ private readonly runtimeOptions;
80
+ /** Creates a production runner unless explicit test boundaries are supplied. */
81
+ constructor(dependencies?: RestrictedSourceRunnerDependencies, runtimeOptions?: SourceCodeRuntimeOptions);
82
+ /** Runs one analyzer and removes every per-run resource on all exits. */
83
+ run(request: RestrictedSourceRunRequest): Promise<RestrictedSourceRunResult>;
84
+ }
85
+ /** Validates and snapshots deployment-provided runtime settings. */
86
+ export declare function validateSourceCodeRuntimeOptions(options: SourceCodeRuntimeOptions): SourceCodeRuntimeOptions;
@@ -0,0 +1,35 @@
1
+ /** Releases one process-wide source-analysis admission slot. */
2
+ export interface SourceAnalysisAdmissionPermit {
3
+ /** Makes the slot available to the next queued analysis. */
4
+ release(): Promise<void>;
5
+ }
6
+ /** Represents the admission boundary consumed by source orchestration. */
7
+ export interface SourceAnalysisAdmissionControllerLike {
8
+ /** Waits for a bounded process-wide analysis slot. */
9
+ acquire(signal?: AbortSignal): Promise<SourceAnalysisAdmissionPermit>;
10
+ }
11
+ /** Configures the process-wide source-analysis admission boundary. */
12
+ export interface SourceAnalysisAdmissionControllerOptions {
13
+ /** Bounds simultaneous analysis filesystems in one tenant process. */
14
+ maxConcurrentAnalyses: number;
15
+ /** Bounds how long a caller waits for a slot. */
16
+ waitTimeoutMs: number;
17
+ /** Overrides the retry interval for deterministic tests. */
18
+ retryIntervalMs?: number;
19
+ /** Isolates a controller namespace for deterministic tests. */
20
+ scope?: string;
21
+ }
22
+ /**
23
+ * Uses operating-system listener ownership as a crash-safe semaphore shared by every worker thread
24
+ * in one tenant process.
25
+ */
26
+ export declare class SourceAnalysisAdmissionController implements SourceAnalysisAdmissionControllerLike {
27
+ private readonly maxConcurrentAnalyses;
28
+ private readonly retryIntervalMs;
29
+ private readonly scope;
30
+ private readonly waitTimeoutMs;
31
+ /** Creates a bounded semaphore whose slots are released automatically if their worker exits. */
32
+ constructor(options: SourceAnalysisAdmissionControllerOptions);
33
+ /** Waits until this tenant process has capacity or the bounded wait ends. */
34
+ acquire(signal?: AbortSignal): Promise<SourceAnalysisAdmissionPermit>;
35
+ }