@agents-at-scale/ark 0.1.46 → 0.1.49

package/dist/commands/marketplace/index.js

@@ -1,7 +1,11 @@
 import { Command } from 'commander';
 import chalk from 'chalk';
-import { getAllMarketplaceServices } from '../../marketplaceServices.js';
+import { getMarketplaceRepoUrl, getMarketplaceRegistry, } from '../../lib/config.js';
+import { getAllMarketplaceServices, getAllMarketplaceAgents, } from '../../marketplaceServices.js';
+import { fetchMarketplaceManifest } from '../../lib/marketplaceFetcher.js';
 function createMarketplaceCommand(_config) {
+    const repoUrl = getMarketplaceRepoUrl();
+    const registry = getMarketplaceRegistry();
     const marketplace = new Command('marketplace');
     marketplace
         .description('Manage marketplace services')
@@ -9,39 +13,63 @@ function createMarketplaceCommand(_config) {
 ${chalk.blue('🏪 ARK Marketplace')}
 Install community-contributed services from the ARK Marketplace.
 
-Repository: ${chalk.cyan('https://github.com/mckinsey/agents-at-scale-marketplace')}
-Registry: ${chalk.cyan('ghcr.io/mckinsey/agents-at-scale-marketplace/charts')}
+Repository: ${chalk.cyan(repoUrl)}
+Registry: ${chalk.cyan(registry.replace('oci://', ''))}
 `)
         .addHelpText('after', `
 ${chalk.cyan('Examples:')}
-  ${chalk.yellow('ark marketplace list')}                        # List available services
-  ${chalk.yellow('ark install marketplace/services/phoenix')}    # Install Phoenix
+  ${chalk.yellow('ark marketplace list')}                        # List available services and agents
+  ${chalk.yellow('ark install marketplace/services/phoenix')}    # Install Phoenix service
+  ${chalk.yellow('ark install marketplace/agents/noah')}         # Install Noah agent
   ${chalk.yellow('ark uninstall marketplace/services/phoenix')}  # Uninstall Phoenix
-  
-${chalk.cyan('Available Services:')}
-  • phoenix  - AI/ML observability and evaluation platform
-  • langfuse - Open-source LLM observability and analytics
 `);
     // List command
     const list = new Command('list');
     list
         .alias('ls')
-        .description('List available marketplace services')
-        .action(() => {
-        const services = getAllMarketplaceServices();
-        console.log(chalk.blue('\n🏪 ARK Marketplace Services\n'));
-        console.log(chalk.gray('Install with: ark install marketplace/services/<service-name>\n'));
-        for (const [key, service] of Object.entries(services)) {
-            const icon = '📦';
-            const serviceName = `marketplace/services/${key.padEnd(12)}`;
-            const serviceDesc = service.description;
-            console.log(`${icon} ${chalk.green(serviceName)} ${chalk.gray(serviceDesc)}`);
-            const namespaceInfo = `namespace: ${service.namespace || 'default'}`;
-            console.log(`   ${chalk.dim(namespaceInfo)}`);
+        .description('List available marketplace services and agents')
+        .action(async () => {
+        const services = await getAllMarketplaceServices();
+        const agents = await getAllMarketplaceAgents();
+        const manifest = await fetchMarketplaceManifest();
+        console.log(chalk.blue('\n🏪 ARK Marketplace\n'));
+        if (!manifest) {
+            console.log(chalk.yellow('⚠️  Marketplace unavailable\n'));
+            console.log(chalk.gray('Could not fetch marketplace.json from repository.\n'));
+            console.log(chalk.cyan(`Repository: ${repoUrl}`));
+            console.log(chalk.cyan(`Registry: ${registry}`));
             console.log();
+            return;
         }
-        console.log(chalk.cyan('Repository: https://github.com/mckinsey/agents-at-scale-marketplace'));
-        console.log(chalk.cyan('Registry: oci://ghcr.io/mckinsey/agents-at-scale-marketplace/charts'));
+        console.log(chalk.dim(`Using marketplace.json (version: ${manifest.version})\n`));
+        if (services && Object.keys(services).length > 0) {
+            console.log(chalk.bold('Services:'));
+            console.log(chalk.gray('Install with: ark install marketplace/services/<name>\n'));
+            for (const [key, service] of Object.entries(services)) {
+                const icon = '📦';
+                const serviceName = `marketplace/services/${key.padEnd(12)}`;
+                const serviceDesc = service.description;
+                console.log(`${icon} ${chalk.green(serviceName)} ${chalk.gray(serviceDesc)}`);
+                const namespaceInfo = `namespace: ${service.namespace || 'default'}`;
+                console.log(`   ${chalk.dim(namespaceInfo)}`);
+                console.log();
+            }
+        }
+        if (agents && Object.keys(agents).length > 0) {
+            console.log(chalk.bold('Agents:'));
+            console.log(chalk.gray('Install with: ark install marketplace/agents/<name>\n'));
+            for (const [key, agent] of Object.entries(agents)) {
+                const icon = '🤖';
+                const agentName = `marketplace/agents/${key.padEnd(12)}`;
+                const agentDesc = agent.description;
+                console.log(`${icon} ${chalk.green(agentName)} ${chalk.gray(agentDesc)}`);
+                const namespaceInfo = `namespace: ${agent.namespace || 'default'}`;
+                console.log(`   ${chalk.dim(namespaceInfo)}`);
+                console.log();
+            }
+        }
+        console.log(chalk.cyan(`Repository: ${repoUrl}`));
+        console.log(chalk.cyan(`Registry: ${registry}`));
         console.log();
     });
     marketplace.addCommand(list);

package/dist/commands/marketplace/index.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/commands/marketplace/index.spec.js

@@ -0,0 +1,88 @@
+import { jest } from '@jest/globals';
+import { Command } from 'commander';
+const mockGetAllMarketplaceServices = jest.fn();
+const mockGetAllMarketplaceAgents = jest.fn();
+const mockFetchMarketplaceManifest = jest.fn();
+const mockConsoleLog = jest.spyOn(console, 'log').mockImplementation(() => { });
+jest.unstable_mockModule('../../marketplaceServices.js', () => ({
+    getAllMarketplaceServices: mockGetAllMarketplaceServices,
+    getAllMarketplaceAgents: mockGetAllMarketplaceAgents,
+}));
+jest.unstable_mockModule('../../lib/marketplaceFetcher.js', () => ({
+    fetchMarketplaceManifest: mockFetchMarketplaceManifest,
+}));
+const { createMarketplaceCommand } = await import('./index.js');
+describe('marketplace command', () => {
+    beforeEach(() => {
+        jest.clearAllMocks();
+    });
+    it('creates marketplace command with correct structure', () => {
+        const command = createMarketplaceCommand({});
+        expect(command).toBeInstanceOf(Command);
+        expect(command.name()).toBe('marketplace');
+    });
+    it('lists services and agents from manifest', async () => {
+        const mockServices = {
+            'test-service': {
+                name: 'test-service',
+                helmReleaseName: 'test-service',
+                description: 'Test service description',
+                enabled: true,
+                category: 'marketplace',
+                namespace: 'test-ns',
+            },
+        };
+        const mockAgents = {
+            'test-agent': {
+                name: 'test-agent',
+                helmReleaseName: 'test-agent',
+                description: 'Test agent description',
+                enabled: true,
+                category: 'marketplace',
+                namespace: 'test-ns',
+            },
+        };
+        const mockManifest = {
+            version: '1.0.0',
+            marketplace: 'ARK Marketplace',
+            items: [
+                {
+                    name: 'test-service',
+                    description: 'Test service',
+                    type: 'service',
+                    ark: {
+                        chartPath: 'oci://registry/test-service',
+                        namespace: 'test',
+                    },
+                },
+                {
+                    name: 'test-agent',
+                    description: 'Test agent',
+                    type: 'agent',
+                    ark: {
+                        chartPath: 'oci://registry/test-agent',
+                        namespace: 'test',
+                    },
+                },
+            ],
+        };
+        mockGetAllMarketplaceServices.mockResolvedValue(mockServices);
+        mockGetAllMarketplaceAgents.mockResolvedValue(mockAgents);
+        mockFetchMarketplaceManifest.mockResolvedValue(mockManifest);
+        const command = createMarketplaceCommand({});
+        await command.parseAsync(['node', 'test', 'list']);
+        expect(mockGetAllMarketplaceServices).toHaveBeenCalled();
+        expect(mockGetAllMarketplaceAgents).toHaveBeenCalled();
+        expect(mockConsoleLog).toHaveBeenCalled();
+    });
+    it('shows unavailable message when marketplace unavailable', async () => {
+        mockGetAllMarketplaceServices.mockResolvedValue(null);
+        mockGetAllMarketplaceAgents.mockResolvedValue(null);
+        mockFetchMarketplaceManifest.mockResolvedValue(null);
+        const command = createMarketplaceCommand({});
+        await command.parseAsync(['node', 'test', 'list']);
+        expect(mockConsoleLog).toHaveBeenCalled();
+        const logCalls = mockConsoleLog.mock.calls.map((c) => c[0]).join(' ');
+        expect(logCalls).toContain('unavailable');
+    });
+});

package/dist/commands/memory/index.js

@@ -1,9 +1,11 @@
 import { Command } from 'commander';
+import { loadConfig } from '../../lib/config.js';
 import output from '../../lib/output.js';
 import { ArkApiProxy } from '../../lib/arkApiProxy.js';
 export async function listSessions(options) {
     try {
-        const proxy = new ArkApiProxy();
+        const config = loadConfig();
+        const proxy = new ArkApiProxy(undefined, config.services?.reusePortForwards ?? false);
         const arkApiClient = await proxy.start();
         const sessions = await arkApiClient.getSessions();
         if (options.output === 'json') {
@@ -27,7 +29,8 @@ export async function listSessions(options) {
 }
 export async function deleteSession(sessionId, options) {
     try {
-        const proxy = new ArkApiProxy();
+        const config = loadConfig();
+        const proxy = new ArkApiProxy(undefined, config.services?.reusePortForwards ?? false);
         const arkApiClient = await proxy.start();
         const response = await arkApiClient.deleteSession(sessionId);
         if (options.output === 'json') {
@@ -44,7 +47,8 @@ export async function deleteSession(sessionId, options) {
 }
 export async function deleteQuery(sessionId, queryId, options) {
     try {
-        const proxy = new ArkApiProxy();
+        const config = loadConfig();
+        const proxy = new ArkApiProxy(undefined, config.services?.reusePortForwards ?? false);
         const arkApiClient = await proxy.start();
         const response = await arkApiClient.deleteQueryMessages(sessionId, queryId);
         if (options.output === 'json') {
@@ -61,7 +65,8 @@ export async function deleteQuery(sessionId, queryId, options) {
 }
 export async function deleteAll(options) {
     try {
-        const proxy = new ArkApiProxy();
+        const config = loadConfig();
+        const proxy = new ArkApiProxy(undefined, config.services?.reusePortForwards ?? false);
         const arkApiClient = await proxy.start();
         const response = await arkApiClient.deleteAllSessions();
         if (options.output === 'json') {

package/dist/commands/models/index.d.ts

@@ -1,3 +1,3 @@
 import { Command } from 'commander';
 import type { ArkConfig } from '../../lib/config.js';
-export declare function createModelsCommand(_: ArkConfig): Command;
+export declare function createModelsCommand(config: ArkConfig): Command;

package/dist/commands/models/index.js

@@ -31,7 +31,7 @@ async function listModels(options) {
         process.exit(1);
     }
 }
-export function createModelsCommand(_) {
+export function createModelsCommand(config) {
     const modelsCommand = new Command('models');
     modelsCommand
         .description('List available models')
@@ -69,11 +69,13 @@ export function createModelsCommand(_) {
         .description('Query a model')
         .argument('<name>', 'Model name (e.g., default)')
         .argument('<message>', 'Message to send')
-        .action(async (name, message) => {
+        .option('--timeout <timeout>', 'Query timeout (e.g., 30s, 5m, 1h)')
+        .action(async (name, message, options) => {
         await executeQuery({
             targetType: 'model',
             targetName: name,
             message,
+            timeout: options.timeout || config.queryTimeout,
         });
     });
     modelsCommand.addCommand(queryCommand);

package/dist/commands/query/index.d.ts

@@ -1,3 +1,3 @@
 import { Command } from 'commander';
 import type { ArkConfig } from '../../lib/config.js';
-export declare function createQueryCommand(_: ArkConfig): Command;
+export declare function createQueryCommand(config: ArkConfig): Command;

package/dist/commands/query/index.js

@@ -2,14 +2,16 @@ import { Command } from 'commander';
 import chalk from 'chalk';
 import { executeQuery, parseTarget } from '../../lib/executeQuery.js';
 import { ExitCodes } from '../../lib/errors.js';
-export function createQueryCommand(_) {
+export function createQueryCommand(config) {
     const queryCommand = new Command('query');
     queryCommand
         .description('Execute a single query against a model or agent')
         .argument('<target>', 'Query target (e.g., model/default, agent/my-agent)')
         .argument('<message>', 'Message to send')
-        .option('-o, --output <format>', 'Output format: yaml, json, or name (prints only resource name)')
+        .option('-o, --output <format>', 'Output format: yaml, json, name or events (shows structured event data)')
+        .option('--timeout <timeout>', 'Query timeout (e.g., 30s, 5m, 1h)')
         .option('--session-id <sessionId>', 'Session ID to associate with the query for conversation continuity')
+        .option('--conversation-id <conversationId>', 'Conversation ID to associate with the query for memory continuity')
         .action(async (target, message, options) => {
         const parsed = parseTarget(target);
         if (!parsed) {
@@ -21,7 +23,9 @@ export function createQueryCommand(_) {
             targetName: parsed.name,
             message,
             outputFormat: options.output,
+            timeout: options.timeout || config.queryTimeout,
             sessionId: options.sessionId,
+            conversationId: options.conversationId,
         });
     });
     return queryCommand;

package/dist/commands/status/index.js

@@ -327,7 +327,12 @@ export function createStatusCommand() {
     statusCommand
         .description('Check ARK system status')
         .argument('[services...]', 'specific services to check (optional)')
-        .option('--wait-for-ready <timeout>', 'wait for services to be ready (e.g., 30s, 2m, 1h)')
-        .action((services, options) => checkStatus(services, options));
+        .option('--wait-for-ready [timeout]', 'wait for services to be ready, e.g, 30s, 2m, 1h (default: 30m)')
+        .action((services, options) => {
+        if (options.waitForReady === true) {
+            options.waitForReady = '30m';
+        }
+        checkStatus(services, options);
+    });
     return statusCommand;
 }

package/dist/commands/teams/index.d.ts

@@ -1,3 +1,3 @@
 import { Command } from 'commander';
 import type { ArkConfig } from '../../lib/config.js';
-export declare function createTeamsCommand(_: ArkConfig): Command;
+export declare function createTeamsCommand(config: ArkConfig): Command;

package/dist/commands/teams/index.js

@@ -29,7 +29,7 @@ async function listTeams(options) {
         process.exit(1);
     }
 }
-export function createTeamsCommand(_) {
+export function createTeamsCommand(config) {
     const teamsCommand = new Command('teams');
     teamsCommand
         .description('List available teams')
@@ -52,11 +52,13 @@ export function createTeamsCommand(_) {
         .description('Query a team')
         .argument('<name>', 'Team name')
         .argument('<message>', 'Message to send')
-        .action(async (name, message) => {
+        .option('--timeout <timeout>', 'Query timeout (e.g., 30s, 5m, 1h)')
+        .action(async (name, message, options) => {
         await executeQuery({
             targetType: 'team',
             targetName: name,
             message,
+            timeout: options.timeout || config.queryTimeout,
         });
     });
     teamsCommand.addCommand(queryCommand);

package/dist/commands/uninstall/index.js

@@ -5,7 +5,7 @@ import inquirer from 'inquirer';
 import { showNoClusterError } from '../../lib/startup.js';
 import output from '../../lib/output.js';
 import { getInstallableServices } from '../../arkServices.js';
-import { isMarketplaceService, extractMarketplaceServiceName, getMarketplaceService, getAllMarketplaceServices, } from '../../marketplaceServices.js';
+import { isMarketplaceService, getMarketplaceItem, getAllMarketplaceServices, getAllMarketplaceAgents, } from '../../marketplaceServices.js';
 async function uninstallService(service, verbose = false) {
     const helmArgs = ['uninstall', service.helmReleaseName, '--ignore-not-found'];
     // Only add namespace flag if service has explicit namespace
@@ -26,20 +26,30 @@ async function uninstallArk(config, serviceName, options = {}) {
     console.log(); // Add blank line after cluster info
     // If a specific service is requested, uninstall only that service
     if (serviceName) {
-        // Check if it's a marketplace service
+        // Check if it's a marketplace item
         if (isMarketplaceService(serviceName)) {
-            const marketplaceServiceName = extractMarketplaceServiceName(serviceName);
-            const service = getMarketplaceService(marketplaceServiceName);
+            const service = await getMarketplaceItem(serviceName);
             if (!service) {
-                output.error(`marketplace service '${marketplaceServiceName}' not found`);
-                output.info('available marketplace services:');
-                const marketplaceServices = getAllMarketplaceServices();
-                for (const serviceName of Object.keys(marketplaceServices)) {
-                    output.info(`  marketplace/services/${serviceName}`);
+                output.error(`marketplace item '${serviceName}' not found`);
+                output.info('available marketplace items:');
+                const marketplaceServices = await getAllMarketplaceServices();
+                if (marketplaceServices) {
+                    for (const name of Object.keys(marketplaceServices)) {
+                        output.info(`  marketplace/services/${name}`);
+                    }
+                }
+                const marketplaceAgents = await getAllMarketplaceAgents();
+                if (marketplaceAgents) {
+                    for (const name of Object.keys(marketplaceAgents)) {
+                        output.info(`  marketplace/agents/${name}`);
+                    }
+                }
+                if (!marketplaceServices && !marketplaceAgents) {
+                    output.warning('Marketplace unavailable');
                 }
                 process.exit(1);
             }
-            output.info(`uninstalling marketplace service ${service.name}...`);
+            output.info(`uninstalling marketplace item ${service.name}...`);
             try {
                 await uninstallService(service, options.verbose);
                 output.success(`${service.name} uninstalled successfully`);

package/dist/index.js

@@ -14,7 +14,9 @@ import { createCompletionCommand } from './commands/completion/index.js';
 import { createDashboardCommand } from './commands/dashboard/index.js';
 import { createDocsCommand } from './commands/docs/index.js';
 import { createEvaluationCommand } from './commands/evaluation/index.js';
+import { createExportCommand } from './commands/export/index.js';
 import { createGenerateCommand } from './commands/generate/index.js';
+import { createImportCommand } from './commands/import/index.js';
 import { createInstallCommand } from './commands/install/index.js';
 import { createMarketplaceCommand } from './commands/marketplace/index.js';
 import { createMemoryCommand } from './commands/memory/index.js';
@@ -48,7 +50,9 @@ async function main() {
     program.addCommand(createDashboardCommand(config));
     program.addCommand(createDocsCommand(config));
     program.addCommand(createEvaluationCommand(config));
+    program.addCommand(createExportCommand(config));
     program.addCommand(createGenerateCommand(config));
+    program.addCommand(createImportCommand(config));
     program.addCommand(createInstallCommand(config));
     program.addCommand(createMarketplaceCommand(config));
     program.addCommand(createMemoryCommand(config));

package/dist/lib/arkApiProxy.d.ts

@@ -1,7 +1,7 @@
 import { ArkApiClient } from './arkApiClient.js';
 export declare class ArkApiProxy {
     private serviceProxy;
-    constructor(localPort?: number);
+    constructor(localPort?: number, reusePortForwards?: boolean);
     start(): Promise<ArkApiClient>;
     stop(): void;
     isRunning(): boolean;

package/dist/lib/arkApiProxy.js

@@ -2,9 +2,9 @@ import { ArkApiClient } from './arkApiClient.js';
 import { ArkServiceProxy } from './arkServiceProxy.js';
 import { arkServices } from '../arkServices.js';
 export class ArkApiProxy {
-    constructor(localPort) {
+    constructor(localPort, reusePortForwards = false) {
         const arkApiService = arkServices['ark-api'];
-        this.serviceProxy = new ArkServiceProxy(arkApiService, localPort);
+        this.serviceProxy = new ArkServiceProxy(arkApiService, localPort, reusePortForwards);
     }
     async start() {
         const arkApiUrl = await this.serviceProxy.start();

package/dist/lib/arkServiceProxy.d.ts

@@ -1,11 +1,13 @@
 import { ArkService } from '../arkServices.js';
 export declare class ArkServiceProxy {
+    private reusePortForwards;
     private kubectlProcess?;
     private localPort;
     private isReady;
     private service;
-    constructor(service: ArkService, localPort?: number);
+    constructor(service: ArkService, localPort?: number, reusePortForwards?: boolean);
     private getRandomPort;
+    private checkExistingPortForward;
     start(): Promise<string>;
     stop(): void;
     isRunning(): boolean;

package/dist/lib/arkServiceProxy.js

@@ -1,6 +1,10 @@
 import { spawn } from 'child_process';
+import find from 'find-process';
+import Debug from 'debug';
+const debug = Debug('ark:service-proxy');
 export class ArkServiceProxy {
-    constructor(service, localPort) {
+    constructor(service, localPort, reusePortForwards = false) {
+        this.reusePortForwards = reusePortForwards;
         this.isReady = false;
         this.service = service;
         this.localPort =
@@ -9,10 +13,39 @@ export class ArkServiceProxy {
     getRandomPort() {
         return Math.floor(Math.random() * (65535 - 1024) + 1024);
     }
+    async checkExistingPortForward() {
+        try {
+            const processes = await find('port', this.localPort);
+            if (processes.length === 0) {
+                return false;
+            }
+            const kubectlProcess = processes.find((proc) => proc.cmd?.includes('kubectl') && proc.cmd?.includes('port-forward'));
+            if (kubectlProcess) {
+                debug(`Reusing existing kubectl port-forward on port ${this.localPort} (PID: ${kubectlProcess.pid})`);
+                this.isReady = true;
+                return true;
+            }
+            const processInfo = processes[0];
+            throw new Error(`${this.service.name} port forward failed: port ${this.localPort} is already in use by ${processInfo.name} (PID: ${processInfo.pid})`);
+        }
+        catch (error) {
+            if (error instanceof Error && error.message.includes('already in use')) {
+                throw error;
+            }
+            debug(`Error checking for existing port-forward: ${error}`);
+            return false;
+        }
+    }
     async start() {
         if (!this.service.k8sServiceName || !this.service.k8sServicePort) {
             throw new Error(`${this.service.name} service configuration missing k8sServiceName or k8sServicePort`);
         }
+        if (this.reusePortForwards) {
+            const isReused = await this.checkExistingPortForward();
+            if (isReused) {
+                return `http://localhost:${this.localPort}`;
+            }
+        }
         return new Promise((resolve, reject) => {
             const args = [
                 'port-forward',

package/dist/lib/arkServiceProxy.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/lib/arkServiceProxy.spec.js

@@ -0,0 +1,100 @@
+import { jest } from '@jest/globals';
+import { Buffer } from 'buffer';
+const mockFind = jest.fn();
+jest.unstable_mockModule('find-process', () => ({
+    default: mockFind,
+}));
+const mockSpawn = jest.fn();
+const mockChildProcess = {
+    spawn: mockSpawn,
+};
+jest.unstable_mockModule('child_process', () => ({
+    ...mockChildProcess,
+    spawn: mockSpawn,
+}));
+const { ArkServiceProxy } = await import('./arkServiceProxy.js');
+describe('ArkServiceProxy', () => {
+    const mockService = {
+        name: 'test-service',
+        helmReleaseName: 'test-service',
+        description: 'Test service',
+        k8sServiceName: 'test-service-k8s',
+        k8sServicePort: 8080,
+        namespace: 'default',
+        enabled: true,
+        category: 'test',
+    };
+    beforeEach(() => {
+        jest.clearAllMocks();
+    });
+    describe('port-forward reuse', () => {
+        it('creates new port-forward when reuse is disabled', async () => {
+            const proxy = new ArkServiceProxy(mockService, 3000, false);
+            const mockProcess = {
+                stdout: { on: jest.fn() },
+                stderr: { on: jest.fn() },
+                on: jest.fn(),
+                kill: jest.fn(),
+            };
+            mockSpawn.mockReturnValue(mockProcess);
+            setTimeout(() => {
+                const stdoutCallback = mockProcess.stdout.on.mock.calls.find((call) => call[0] === 'data')?.[1];
+                if (stdoutCallback) {
+                    stdoutCallback(Buffer.from('Forwarding from 127.0.0.1:3000'));
+                }
+            }, 10);
+            const url = await proxy.start();
+            expect(url).toBe('http://localhost:3000');
+            expect(mockFind).not.toHaveBeenCalled();
+            expect(mockSpawn).toHaveBeenCalledWith('kubectl', ['port-forward', 'service/test-service-k8s', '3000:8080', '--namespace', 'default'], expect.any(Object));
+        });
+        it('reuses existing kubectl port-forward when reuse is enabled', async () => {
+            mockFind.mockResolvedValue([
+                {
+                    pid: 12345,
+                    name: 'kubectl',
+                    cmd: 'kubectl port-forward service/test-service-k8s 3000:8080',
+                },
+            ]);
+            const proxy = new ArkServiceProxy(mockService, 3000, true);
+            const url = await proxy.start();
+            expect(url).toBe('http://localhost:3000');
+            expect(mockFind).toHaveBeenCalledWith('port', 3000);
+            expect(mockSpawn).not.toHaveBeenCalled();
+        });
+        it('creates new port-forward when port is not in use', async () => {
+            mockFind.mockResolvedValue([]);
+            const proxy = new ArkServiceProxy(mockService, 3000, true);
+            const mockProcess = {
+                stdout: { on: jest.fn() },
+                stderr: { on: jest.fn() },
+                on: jest.fn(),
+                kill: jest.fn(),
+            };
+            mockSpawn.mockReturnValue(mockProcess);
+            setTimeout(() => {
+                const stdoutCallback = mockProcess.stdout.on.mock.calls.find((call) => call[0] === 'data')?.[1];
+                if (stdoutCallback) {
+                    stdoutCallback(Buffer.from('Forwarding from 127.0.0.1:3000'));
+                }
+            }, 10);
+            const url = await proxy.start();
+            expect(url).toBe('http://localhost:3000');
+            expect(mockFind).toHaveBeenCalledWith('port', 3000);
+            expect(mockSpawn).toHaveBeenCalled();
+        });
+        it('throws error when port is in use by non-kubectl process', async () => {
+            mockFind.mockResolvedValue([
+                {
+                    pid: 54321,
+                    name: 'node',
+                    cmd: 'node server.js',
+                },
+            ]);
+            const proxy = new ArkServiceProxy(mockService, 3000, true);
+            await expect(proxy.start()).rejects.toThrow('test-service port forward failed: port 3000 is already in use by node (PID: 54321)');
+            expect(mockFind).toHaveBeenCalledWith('port', 3000);
+            expect(mockSpawn).not.toHaveBeenCalled();
+        });
+    });
+});

package/dist/lib/chatClient.d.ts

@@ -6,6 +6,8 @@ export interface ChatConfig {
     currentTarget?: QueryTarget;
     a2aContextId?: string;
     sessionId?: string;
+    conversationId?: string;
+    queryTimeout?: string;
 }
 export interface ToolCall {
     id: string;

package/dist/lib/chatClient.js

@@ -17,12 +17,20 @@ export class ChatClient {
             signal: signal,
         };
         // Build metadata object - only add if we have something to include
-        if (config.sessionId || config.a2aContextId) {
+        if (config.sessionId ||
+            config.conversationId ||
+            config.a2aContextId ||
+            config.queryTimeout) {
             params.metadata = {};
-            // Add sessionId directly to metadata (goes to spec, not annotations)
             if (config.sessionId) {
                 params.metadata.sessionId = config.sessionId;
             }
+            if (config.conversationId) {
+                params.metadata.conversationId = config.conversationId;
+            }
+            if (config.queryTimeout) {
+                params.metadata.timeout = config.queryTimeout;
+            }
             // Add A2A context ID to queryAnnotations (goes to annotations)
             if (config.a2aContextId) {
                 const queryAnnotations = {