@salesforce/sfdx-agent-harness-claude 0.1.0

package/dist/claude-query-env-builder.d.ts

@@ -0,0 +1,20 @@
+import type { JSONWebToken } from '@salesforce/llm-gateway-sdk';
+import type { ClaudeTransportResolver } from './claude-transport-resolver.js';
+export interface ClaudeQueryEnvBuildResult {
+    env: Record<string, string | undefined>;
+    nativeModelId: string;
+}
+/**
+ * Assembles the environment variable map for a Claude subprocess spawn.
+ *
+ * Layering order (last wins):
+ * 1. Inherited process env (with dangerous vars stripped)
+ * 2. Resolver-provided vars (auth, transport flags, endpoint config)
+ */
+export declare class ClaudeQueryEnvBuilder {
+    private readonly resolver;
+    private readonly storageRootFolder?;
+    private readonly processEnv;
+    constructor(resolver: ClaudeTransportResolver, storageRootFolder?: string | undefined, processEnv?: Record<string, string | undefined>);
+    build(orgJwt: JSONWebToken, modelId: string): Promise<ClaudeQueryEnvBuildResult>;
+}

package/dist/claude-query-env-builder.js

@@ -0,0 +1,37 @@
+/*
+ * Copyright 2026, Salesforce, Inc. All rights reserved.
+ * See LICENSE.txt for license terms.
+ */
+const STRIPPED_ENV_VARS = ['ANTHROPIC_API_KEY', 'ANTHROPIC_AUTH_TOKEN', 'ANTHROPIC_BASE_URL'];
+/**
+ * Assembles the environment variable map for a Claude subprocess spawn.
+ *
+ * Layering order (last wins):
+ * 1. Inherited process env (with dangerous vars stripped)
+ * 2. Resolver-provided vars (auth, transport flags, endpoint config)
+ */
+export class ClaudeQueryEnvBuilder {
+    resolver;
+    storageRootFolder;
+    processEnv;
+    constructor(resolver, storageRootFolder, processEnv = process.env) {
+        this.resolver = resolver;
+        this.storageRootFolder = storageRootFolder;
+        this.processEnv = processEnv;
+    }
+    async build(orgJwt, modelId) {
+        const resolved = await this.resolver.resolve(orgJwt, modelId);
+        const env = { ...this.processEnv };
+        for (const key of STRIPPED_ENV_VARS)
+            delete env[key];
+        return {
+            env: {
+                ...env,
+                ...resolved.env,
+                ...(this.storageRootFolder ? { CLAUDE_CONFIG_DIR: this.storageRootFolder } : {}),
+            },
+            nativeModelId: resolved.nativeModelId,
+        };
+    }
+}
+//# sourceMappingURL=claude-query-env-builder.js.map

package/dist/claude-query-env-builder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"claude-query-env-builder.js","sourceRoot":"","sources":["../src/claude-query-env-builder.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAKH,MAAM,iBAAiB,GAAG,CAAC,mBAAmB,EAAE,sBAAsB,EAAE,oBAAoB,CAAU,CAAC;AAOvG;;;;;;GAMG;AACH,MAAM,OAAO,qBAAqB;IAET;IACA;IACA;IAHrB,YACqB,QAAiC,EACjC,iBAA0B,EAC1B,aAAiD,OAAO,CAAC,GAAG;QAF5D,aAAQ,GAAR,QAAQ,CAAyB;QACjC,sBAAiB,GAAjB,iBAAiB,CAAS;QAC1B,eAAU,GAAV,UAAU,CAAkD;IAC9E,CAAC;IAEJ,KAAK,CAAC,KAAK,CAAC,MAAoB,EAAE,OAAe;QAC7C,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAE9D,MAAM,GAAG,GAAuC,EAAE,GAAG,IAAI,CAAC,UAAU,EAAE,CAAC;QACvE,KAAK,MAAM,GAAG,IAAI,iBAAiB;YAAE,OAAO,GAAG,CAAC,GAAG,CAAC,CAAC;QAErD,OAAO;YACH,GAAG,EAAE;gBACD,GAAG,GAAG;gBACN,GAAG,QAAQ,CAAC,GAAG;gBACf,GAAG,CAAC,IAAI,CAAC,iBAAiB,CAAC,CAAC,CAAC,EAAE,iBAAiB,EAAE,IAAI,CAAC,iBAAiB,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aACnF;YACD,aAAa,EAAE,QAAQ,CAAC,aAAa;SACxC,CAAC;IACN,CAAC;CACJ"}

package/dist/claude-query-options-builder.d.ts

@@ -0,0 +1,26 @@
+import type { Options } from '@anthropic-ai/claude-agent-sdk';
+import type { HarnessAgentConfig, StreamOptions } from '@salesforce/sfdx-agent-sdk';
+/**
+ * Consumer-facing query defaults. Excludes fields the harness must control.
+ */
+export type ClaudeQueryDefaults = Partial<Omit<Options, 'env' | 'includePartialMessages' | 'prompt' | 'model' | 'permissionMode' | 'allowDangerouslySkipPermissions'>>;
+export type SessionOptions = {
+    sessionId?: string;
+    resume?: string;
+};
+/**
+ * Assembles the query() options from layered sources.
+ *
+ * Precedence (last wins):
+ * 1. queryDefaults (factory-level, AFV-provided)
+ * 2. Per-agent options (mapped from HarnessAgentConfig/StreamOptions)
+ * 3. Session options (sessionId or resume for continuity)
+ * 4. Harness-required options (non-overridable operational concerns)
+ */
+export declare class ClaudeQueryOptionsBuilder {
+    private readonly queryDefaults;
+    constructor(queryDefaults?: ClaudeQueryDefaults);
+    build(projectRoot: string, config: HarnessAgentConfig, streamOptions: StreamOptions | undefined, env: Record<string, string | undefined>, sessionOptions?: SessionOptions, nativeModelId?: string): Options & {
+        env: Record<string, string | undefined>;
+    };
+}

package/dist/claude-query-options-builder.js

@@ -0,0 +1,40 @@
+/*
+ * Copyright 2026, Salesforce, Inc. All rights reserved.
+ * See LICENSE.txt for license terms.
+ */
+const HARNESS_REQUIRED_OPTIONS = {
+    includePartialMessages: true,
+    settingSources: [],
+    persistSession: true,
+};
+/**
+ * Assembles the query() options from layered sources.
+ *
+ * Precedence (last wins):
+ * 1. queryDefaults (factory-level, AFV-provided)
+ * 2. Per-agent options (mapped from HarnessAgentConfig/StreamOptions)
+ * 3. Session options (sessionId or resume for continuity)
+ * 4. Harness-required options (non-overridable operational concerns)
+ */
+export class ClaudeQueryOptionsBuilder {
+    queryDefaults;
+    constructor(queryDefaults = {}) {
+        this.queryDefaults = queryDefaults;
+    }
+    build(projectRoot, config, streamOptions, env, sessionOptions, nativeModelId) {
+        const perAgentOptions = {
+            cwd: projectRoot,
+            ...(nativeModelId ? { model: nativeModelId } : {}),
+            ...(config.instructions ? { systemPrompt: config.instructions } : {}),
+            ...(streamOptions?.maxSteps ? { maxTurns: streamOptions.maxSteps } : {}),
+        };
+        return {
+            ...this.queryDefaults,
+            ...perAgentOptions,
+            ...sessionOptions,
+            ...HARNESS_REQUIRED_OPTIONS,
+            env,
+        };
+    }
+}
+//# sourceMappingURL=claude-query-options-builder.js.map

package/dist/claude-query-options-builder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"claude-query-options-builder.js","sourceRoot":"","sources":["../src/claude-query-options-builder.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAeH,MAAM,wBAAwB,GAAqB;IAC/C,sBAAsB,EAAE,IAAI;IAC5B,cAAc,EAAE,EAAE;IAClB,cAAc,EAAE,IAAI;CACvB,CAAC;AAIF;;;;;;;;GAQG;AACH,MAAM,OAAO,yBAAyB;IACL;IAA7B,YAA6B,gBAAqC,EAAE;QAAvC,kBAAa,GAAb,aAAa,CAA0B;IAAG,CAAC;IAExE,KAAK,CACD,WAAmB,EACnB,MAA0B,EAC1B,aAAwC,EACxC,GAAuC,EACvC,cAA+B,EAC/B,aAAsB;QAEtB,MAAM,eAAe,GAAqB;YACtC,GAAG,EAAE,WAAW;YAChB,GAAG,CAAC,aAAa,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,aAAa,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAClD,GAAG,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,MAAM,CAAC,YAAY,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACrE,GAAG,CAAC,aAAa,EAAE,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,aAAa,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAC3E,CAAC;QAEF,OAAO;YACH,GAAG,IAAI,CAAC,aAAa;YACrB,GAAG,eAAe;YAClB,GAAG,cAAc;YACjB,GAAG,wBAAwB;YAC3B,GAAG;SACN,CAAC;IACN,CAAC;CACJ"}

package/dist/claude-transport-resolver.d.ts

@@ -0,0 +1,21 @@
+import type { JSONWebToken } from '@salesforce/llm-gateway-sdk';
+/**
+ * Result of resolving transport configuration for a Claude subprocess.
+ */
+export interface ClaudeTransportResolverResult {
+    /** Environment variables for authenticated communication with the model endpoint. */
+    env: Record<string, string>;
+    /** The native model identifier the subprocess should use (e.g., `'anthropic.claude-sonnet-4-6'`). */
+    nativeModelId: string;
+}
+/**
+ * Resolves all deployment-transport concerns for a Claude subprocess: environment
+ * variables (auth, endpoint, transport flags) and the native model identifier.
+ *
+ * Implementations own transport-specific knowledge: URL derivation, header
+ * serialization, Bedrock vs direct API flags, and the gateway-to-native model
+ * name mapping. The harness treats the result as opaque configuration.
+ */
+export interface ClaudeTransportResolver {
+    resolve(orgJwt: JSONWebToken, modelId: string): Promise<ClaudeTransportResolverResult>;
+}

package/dist/claude-transport-resolver.js

@@ -0,0 +1,6 @@
+/*
+ * Copyright 2026, Salesforce, Inc. All rights reserved.
+ * See LICENSE.txt for license terms.
+ */
+export {};
+//# sourceMappingURL=claude-transport-resolver.js.map

package/dist/claude-transport-resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"claude-transport-resolver.js","sourceRoot":"","sources":["../src/claude-transport-resolver.ts"],"names":[],"mappings":"AAAA;;;GAGG"}

package/dist/direct-claude-transport-resolver.d.ts

@@ -0,0 +1,13 @@
+import type { JSONWebToken } from '@salesforce/llm-gateway-sdk';
+import type { ClaudeTransportResolver, ClaudeTransportResolverResult } from './claude-transport-resolver.js';
+/**
+ * Resolver for direct Anthropic API access (no gateway, no Bedrock shim).
+ * Intended for local development and testing without a Salesforce org.
+ *
+ * Analogous to `LLMGExpressMastraModelConfigFactory` in the Mastra harness.
+ */
+export declare class DirectClaudeTransportResolver implements ClaudeTransportResolver {
+    private readonly getApiKey;
+    constructor(getApiKey: () => string);
+    resolve(_orgJwt: JSONWebToken, modelId: string): Promise<ClaudeTransportResolverResult>;
+}

package/dist/direct-claude-transport-resolver.js

@@ -0,0 +1,23 @@
+/*
+ * Copyright 2026, Salesforce, Inc. All rights reserved.
+ * See LICENSE.txt for license terms.
+ */
+/**
+ * Resolver for direct Anthropic API access (no gateway, no Bedrock shim).
+ * Intended for local development and testing without a Salesforce org.
+ *
+ * Analogous to `LLMGExpressMastraModelConfigFactory` in the Mastra harness.
+ */
+export class DirectClaudeTransportResolver {
+    getApiKey;
+    constructor(getApiKey) {
+        this.getApiKey = getApiKey;
+    }
+    async resolve(_orgJwt, modelId) {
+        return {
+            env: { ANTHROPIC_API_KEY: this.getApiKey() },
+            nativeModelId: modelId,
+        };
+    }
+}
+//# sourceMappingURL=direct-claude-transport-resolver.js.map

package/dist/direct-claude-transport-resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"direct-claude-transport-resolver.js","sourceRoot":"","sources":["../src/direct-claude-transport-resolver.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAKH;;;;;GAKG;AACH,MAAM,OAAO,6BAA6B;IACT;IAA7B,YAA6B,SAAuB;QAAvB,cAAS,GAAT,SAAS,CAAc;IAAG,CAAC;IAExD,KAAK,CAAC,OAAO,CAAC,OAAqB,EAAE,OAAe;QAChD,OAAO;YACH,GAAG,EAAE,EAAE,iBAAiB,EAAE,IAAI,CAAC,SAAS,EAAE,EAAE;YAC5C,aAAa,EAAE,OAAO;SACzB,CAAC;IACN,CAAC;CACJ"}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { ClaudeHarnessFactory, type ClaudeHarnessFactoryConfig } from './claude-harness-factory.js';
+export { type ClaudeTransportResolver, type ClaudeTransportResolverResult } from './claude-transport-resolver.js';
+export { type ClaudeQueryDefaults } from './claude-query-options-builder.js';
+export { DirectClaudeTransportResolver } from './direct-claude-transport-resolver.js';

package/dist/index.js

@@ -0,0 +1,9 @@
+/*
+ * Copyright 2026, Salesforce, Inc. All rights reserved.
+ * See LICENSE.txt for license terms.
+ */
+export { ClaudeHarnessFactory } from './claude-harness-factory.js';
+export {} from './claude-transport-resolver.js';
+export {} from './claude-query-options-builder.js';
+export { DirectClaudeTransportResolver } from './direct-claude-transport-resolver.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,oBAAoB,EAAmC,MAAM,6BAA6B,CAAC;AACpG,OAAO,EAAoE,MAAM,gCAAgC,CAAC;AAClH,OAAO,EAA4B,MAAM,mCAAmC,CAAC;AAC7E,OAAO,EAAE,6BAA6B,EAAE,MAAM,uCAAuC,CAAC"}