newo 3.7.3 → 3.7.5

package/dist/domain/strategies/sync/V2ProjectSyncStrategy.js

@@ -14,13 +14,14 @@
  *           skills/{SkillIdn}.nsl|.nslg
  */
 import fs from 'fs-extra';
-import { listProjects, listAgents, listFlowSkills, listFlowEvents, listFlowStates, updateSkill, publishFlow, getProjectAttributes, getCustomerAttributes, listLibraries, updateLibrarySkill, getFlow, } from '../../../api.js';
+import path from 'path';
+import { listProjects, listAgents, listFlowSkills, listFlowEvents, listFlowStates, createSkill, createSkillParameter, updateSkill, publishFlow, getProjectAttributes, getCustomerAttributes, listLibraries, updateLibrarySkill, getFlow, } from '../../../api.js';
 import { syncFlowMetadata, emptyFlowSyncCounts, totalFlowSyncOps, describeFlowSyncCounts } from '../../../sync/flow-metadata.js';
 import { ensureStateOnly, writeFileSafe, mapPath, } from '../../../fsutil.js';
 import { sha256, saveHashes, loadHashes } from '../../../hash.js';
-import { v2ImportVersionPath, v2ProjectYamlPath, v2AgentYamlPath, v2FlowYamlPath, v2SkillScriptPath, v2SkillRelativePath, v2ProjectAttributesPath, v2CustomerAttributesPath, v2AkbDir, v2AkbPath, v2LibraryYamlPath, v2LibrarySkillScriptPath, v2LibrarySkillRelativePath, } from '../../../format/paths-v2.js';
+import { v2ImportVersionPath, v2ProjectYamlPath, v2AgentDir, v2AgentYamlPath, v2FlowYamlPath, v2SkillScriptPath, v2SkillRelativePath, v2ProjectAttributesPath, v2CustomerAttributesPath, v2AkbDir, v2AkbPath, v2LibraryYamlPath, v2LibrarySkillScriptPath, v2LibrarySkillRelativePath, } from '../../../format/paths-v2.js';
 import { V2_IMPORT_VERSION, } from '../../../format/types.js';
-import { generateV2FlowYaml, generateV2ProjectYaml, generateV2AgentYaml, buildV2InlineSkill, buildV2FlowEvent, buildV2StateField, parseV2FlowYaml, } from '../../../format/v2-yaml.js';
+import { generateV2FlowYaml, generateV2ProjectYaml, generateV2AgentYaml, parseV2FlowYaml, buildV2InlineSkill, buildV2FlowEvent, buildV2StateField, } from '../../../format/v2-yaml.js';
 import { isContentDifferent } from '../../../sync/skill-files.js';
 import yaml from 'js-yaml';
 import { patchYamlToPyyaml } from '../../../format/yaml-patch.js';
@@ -438,8 +439,15 @@ export class V2ProjectSyncStrategy {
             return result;
         }
         const mapData = await fs.readJson(mapFile);
+        const metadataSync = await this.syncV2FlowYamlDefinitions(client, customer, mapData, newHashes);
+        result.created += metadataSync.created;
+        result.updated += metadataSync.updated;
+        result.errors.push(...metadataSync.errors);
         for (const change of changes) {
             try {
+                if (metadataSync.syncedPaths.has(change.path)) {
+                    continue;
+                }
                 if (change.operation === 'modified') {
                     // V2 flow YAML: newo_customers/{cust}/{proj}/agents/{agent}/flows/{flow}/{flow}.yaml
                     // The flow YAML carries title, events, and state_fields inline, so
@@ -453,7 +461,7 @@ export class V2ProjectSyncStrategy {
                     const isLibrary = change.path.includes('/libraries/');
                     const count = isLibrary
                         ? await this.pushV2LibrarySkillUpdate(client, change, mapData, newHashes)
-                        : await this.pushV2SkillUpdate(client, change, mapData, newHashes);
+                        : await this.pushV2SkillUpdate(client, change, mapData, newHashes, customer.idn);
                     result.updated += count;
                 }
             }
@@ -461,6 +469,9 @@ export class V2ProjectSyncStrategy {
                 result.errors.push(`Failed to push ${change.path}: ${error instanceof Error ? error.message : String(error)}`);
             }
         }
+        if (metadataSync.created > 0 || metadataSync.updated > 0) {
+            await writeFileSafe(mapFile, JSON.stringify(mapData, null, 2));
+        }
         await saveHashes(newHashes, customer.idn);
         if (result.created > 0 || result.updated > 0) {
             await this.publishAllFlows(client, mapData);
@@ -564,28 +575,256 @@ export class V2ProjectSyncStrategy {
         newHashes[change.path] = sha256(content);
         return total;
     }
+    /**
+     * Reconcile inline skill definitions from V2 flow YAML before pushing scripts.
+     *
+     * V2 keeps skill metadata (model, runner_type, parameters) in the flow YAML,
+     * not in a separate skill metadata file. The map only contains the remote IDs
+     * from a previous pull, so new local skills must be created before their
+     * callers can be published.
+     */
+    async syncV2FlowYamlDefinitions(client, customer, mapData, newHashes) {
+        let created = 0;
+        let updated = 0;
+        const syncedPaths = new Set();
+        const errors = [];
+        for (const [projectIdn, projectData] of Object.entries(mapData.projects)) {
+            for (const [agentIdn, agentData] of Object.entries(projectData.agents)) {
+                for (const [flowIdn, flowData] of Object.entries(agentData.flows)) {
+                    const flowYamlPath = v2FlowYamlPath(customer.idn, projectIdn, agentIdn, flowIdn);
+                    if (!(await fs.pathExists(flowYamlPath))) {
+                        continue;
+                    }
+                    let flowDef;
+                    try {
+                        flowDef = await parseV2FlowYaml(flowYamlPath);
+                    }
+                    catch (error) {
+                        this.logger.warn(`[newo_v2] Failed to parse flow YAML ${flowYamlPath}: ${error instanceof Error ? error.message : String(error)}`);
+                        continue;
+                    }
+                    for (const skill of flowDef.skills || []) {
+                        const skillLocator = `${projectIdn}/${agentIdn}/${flowIdn}/${skill.idn}`;
+                        // Per-skill failure isolation: one broken skill must not abort the
+                        // push of every other project/flow in the workspace.
+                        try {
+                            const runnerType = this.normalizeRunnerType(skill.runner_type);
+                            const scriptPath = await this.resolveV2FlowSkillScriptPath(customer.idn, projectIdn, agentIdn, flowIdn, skill.idn, runnerType, skill.prompt_script);
+                            if (!(await fs.pathExists(scriptPath))) {
+                                errors.push(`[newo_v2] Missing script for skill ${skillLocator}: ${scriptPath}`);
+                                continue;
+                            }
+                            const content = await fs.readFile(scriptPath, 'utf8');
+                            const localMetadata = this.buildV2SkillMetadataFromYaml(skill, flowDef, runnerType, flowData.skills[skill.idn]);
+                            const existingSkill = flowData.skills[skill.idn];
+                            if (!existingSkill) {
+                                this.assertSkillModelResolved(localMetadata, skillLocator);
+                                try {
+                                    const createdSkill = await createSkill(client, flowData.id, {
+                                        idn: localMetadata.idn,
+                                        title: localMetadata.title,
+                                        prompt_script: content,
+                                        runner_type: localMetadata.runner_type,
+                                        model: localMetadata.model,
+                                        parameters: localMetadata.parameters,
+                                        path: localMetadata.path || ''
+                                    });
+                                    // The create endpoint ignores inline `parameters` (verified
+                                    // against the live platform) — create them explicitly.
+                                    await this.createMissingSkillParameters(client, { ...localMetadata, id: createdSkill.id, parameters: [] }, localMetadata);
+                                    flowData.skills[skill.idn] = {
+                                        ...localMetadata,
+                                        id: createdSkill.id
+                                    };
+                                    newHashes[scriptPath] = sha256(content);
+                                    syncedPaths.add(scriptPath);
+                                    created++;
+                                    this.logger.info(`[newo_v2] Created skill: ${flowIdn}/${skill.idn}`);
+                                }
+                                catch (error) {
+                                    if (!this.isAlreadyExistsApiError(error)) {
+                                        throw error;
+                                    }
+                                    const remoteSkills = await listFlowSkills(client, flowData.id);
+                                    const remoteSkill = remoteSkills.find(s => s.idn === skill.idn);
+                                    if (!remoteSkill) {
+                                        throw error;
+                                    }
+                                    const remoteMetadata = {
+                                        id: remoteSkill.id,
+                                        idn: remoteSkill.idn,
+                                        title: remoteSkill.title,
+                                        runner_type: remoteSkill.runner_type,
+                                        model: remoteSkill.model,
+                                        parameters: this.normalizeParameters(remoteSkill.parameters),
+                                        path: remoteSkill.path
+                                    };
+                                    await this.createMissingSkillParameters(client, remoteMetadata, localMetadata);
+                                    await updateSkill(client, {
+                                        id: remoteSkill.id,
+                                        title: localMetadata.title,
+                                        idn: localMetadata.idn,
+                                        prompt_script: content,
+                                        runner_type: localMetadata.runner_type,
+                                        model: localMetadata.model,
+                                        parameters: localMetadata.parameters,
+                                        path: remoteSkill.path || localMetadata.path
+                                    });
+                                    flowData.skills[skill.idn] = {
+                                        ...localMetadata,
+                                        id: remoteSkill.id,
+                                        path: remoteSkill.path || localMetadata.path
+                                    };
+                                    newHashes[scriptPath] = sha256(content);
+                                    syncedPaths.add(scriptPath);
+                                    updated++;
+                                    this.logger.info(`[newo_v2] Reused existing skill: ${flowIdn}/${skill.idn}`);
+                                }
+                                continue;
+                            }
+                            const createdParameters = await this.createMissingSkillParameters(client, existingSkill, localMetadata);
+                            if (createdParameters > 0 || this.skillMetadataDiffers(existingSkill, localMetadata)) {
+                                this.assertSkillModelResolved(localMetadata, skillLocator);
+                                await updateSkill(client, {
+                                    id: existingSkill.id,
+                                    title: localMetadata.title,
+                                    idn: localMetadata.idn,
+                                    prompt_script: content,
+                                    runner_type: localMetadata.runner_type,
+                                    model: localMetadata.model,
+                                    parameters: localMetadata.parameters,
+                                    path: localMetadata.path
+                                });
+                                flowData.skills[skill.idn] = {
+                                    ...localMetadata,
+                                    id: existingSkill.id
+                                };
+                                newHashes[scriptPath] = sha256(content);
+                                syncedPaths.add(scriptPath);
+                                updated++;
+                                this.logger.info(`[newo_v2] Updated skill metadata: ${flowIdn}/${skill.idn}`);
+                            }
+                        }
+                        catch (error) {
+                            errors.push(`Failed to sync skill ${skillLocator}: ${error instanceof Error ? error.message : String(error)}`);
+                        }
+                    }
+                }
+            }
+        }
+        return { created, updated, syncedPaths, errors };
+    }
+    async createMissingSkillParameters(client, existing, local) {
+        const existingNames = new Set(this.normalizeParameters(existing.parameters).map(p => p.name));
+        let created = 0;
+        for (const parameter of local.parameters) {
+            if (existingNames.has(parameter.name)) {
+                continue;
+            }
+            try {
+                await createSkillParameter(client, existing.id, {
+                    name: parameter.name,
+                    default_value: parameter.default_value ?? ''
+                });
+                created++;
+                this.logger.info(`[newo_v2] Created skill parameter: ${local.idn}/${parameter.name}`);
+            }
+            catch (error) {
+                if (!this.isAlreadyExistsApiError(error)) {
+                    throw error;
+                }
+            }
+            existingNames.add(parameter.name);
+        }
+        return created;
+    }
+    /**
+     * Detect "resource already exists" API errors.
+     *
+     * Matches only on the precise phrases the platform actually returns
+     * ("already exists", "duplicate key"). Loose substrings like "exist"
+     * would otherwise sweep up unrelated "does not exist" / "doesn't exist"
+     * errors and trigger an incorrect reuse fallback.
+     */
+    isAlreadyExistsApiError(error) {
+        const response = error?.response;
+        const status = response?.status;
+        if (status !== 400 && status !== 409 && status !== 422) {
+            return false;
+        }
+        const haystack = JSON.stringify(response?.data ?? (error instanceof Error ? error.message : String(error))).toLowerCase();
+        return haystack.includes('already exists') || haystack.includes('duplicate key');
+    }
+    normalizeRunnerType(runnerType) {
+        return runnerType === 'nsl' ? 'nsl' : 'guidance';
+    }
+    normalizeParameters(parameters) {
+        return (parameters || []).map(p => ({
+            name: p.name,
+            default_value: p.default_value ?? ''
+        }));
+    }
+    /**
+     * Fail fast if no model could be resolved for a V2 skill.
+     *
+     * `buildV2SkillMetadataFromYaml` falls back to empty strings when neither
+     * the skill nor the flow declare a model. The platform rejects empty
+     * model_idn/provider_idn at creation/update time, but the error it returns
+     * is generic — we surface a clearer message before issuing the request.
+     */
+    assertSkillModelResolved(metadata, locator) {
+        if (!metadata.model.model_idn || !metadata.model.provider_idn) {
+            throw new Error(`[newo_v2] Cannot resolve model for skill ${locator}: ` +
+                `model_idn="${metadata.model.model_idn}", provider_idn="${metadata.model.provider_idn}". ` +
+                `Set either skill.model.* or flow default_model_idn/default_provider_idn in the flow YAML.`);
+        }
+    }
+    buildV2SkillMetadataFromYaml(skill, flowDef, runnerType, existing) {
+        return {
+            id: existing?.id || '',
+            idn: skill.idn,
+            title: skill.title || '',
+            runner_type: runnerType,
+            model: {
+                model_idn: skill.model?.model_idn || flowDef.default_model_idn || '',
+                provider_idn: skill.model?.provider_idn || flowDef.default_provider_idn || ''
+            },
+            parameters: this.normalizeParameters(skill.parameters),
+            path: existing?.path || ''
+        };
+    }
+    skillMetadataDiffers(existing, local) {
+        // Compare model/parameters field-by-field, never via JSON.stringify of the
+        // raw objects: the map stores model keys in platform API order
+        // (provider_idn first) while YAML-built metadata uses model_idn first, and
+        // a key-order-sensitive comparison flags every skill as changed.
+        const paramsKey = (params) => JSON.stringify(this.normalizeParameters(params).sort((a, b) => a.name.localeCompare(b.name)));
+        return (existing.title !== local.title ||
+            existing.runner_type !== local.runner_type ||
+            existing.model.model_idn !== local.model.model_idn ||
+            existing.model.provider_idn !== local.model.provider_idn ||
+            paramsKey(existing.parameters) !== paramsKey(local.parameters));
+    }
+    async resolveV2FlowSkillScriptPath(customerIdn, projectIdn, agentIdn, flowIdn, skillIdn, runnerType, promptScript) {
+        if (promptScript) {
+            const fromPromptScript = `${v2AgentDir(customerIdn, projectIdn, agentIdn)}/${promptScript}`;
+            if (await fs.pathExists(fromPromptScript)) {
+                return fromPromptScript;
+            }
+        }
+        return v2SkillScriptPath(customerIdn, projectIdn, agentIdn, flowIdn, skillIdn, runnerType);
+    }
     /**
      * Push a V2 skill update
      *
      * V2 path: newo_customers/{cust}/{proj}/agents/{agent}/flows/{flow}/skills/{skill}.nsl
      */
-    async pushV2SkillUpdate(client, change, mapData, newHashes) {
-        // Parse V2 path to extract entity hierarchy
-        // Path: .../newo_customers/{cust}/{proj}/agents/{agent}/flows/{flow}/skills/{skillFile}
-        const pathParts = change.path.split('/');
-        const skillFileName = pathParts[pathParts.length - 1] || '';
-        const skillIdn = skillFileName.replace(/\.(nsl|nslg|jinja|guidance)$/, '');
-        // skills/ -> flow/ -> flows/ -> agent/ -> agents/ -> project/
-        const flowIdn = pathParts[pathParts.length - 3] || '';
-        const agentIdn = pathParts[pathParts.length - 5] || '';
-        const projectIdn = pathParts[pathParts.length - 7] || '';
-        // Look up skill in map
-        const projectData = mapData.projects[projectIdn];
-        const agentData = projectData?.agents[agentIdn];
-        const flowData = agentData?.flows[flowIdn];
-        const skillData = flowData?.skills[skillIdn];
-        if (!skillData) {
-            throw new Error(`Skill ${skillIdn} not found in project map (path: ${change.path})`);
+    async pushV2SkillUpdate(client, change, mapData, newHashes, customerIdn) {
+        const target = await this.resolveV2SkillTargetForScriptPath(customerIdn, change.path, mapData) ||
+            this.resolveV2SkillTargetFromCanonicalPath(change.path, mapData);
+        const skillData = target?.skillData;
+        if (!target || !skillData) {
+            throw new Error(`Skill not found in project map (path: ${change.path})`);
         }
         // Read updated script content
         const content = await fs.readFile(change.path, 'utf8');
@@ -601,9 +840,67 @@ export class V2ProjectSyncStrategy {
             path: skillData.path
         });
         newHashes[change.path] = sha256(content);
-        this.logger.info(`[newo_v2] Pushed: ${skillIdn}`);
+        this.logger.info(`[newo_v2] Pushed: ${target.skillIdn}`);
         return 1;
     }
+    normalizePathForComparison(filePath) {
+        return path.resolve(filePath).replace(/\\/g, '/');
+    }
+    async resolveV2SkillTargetForScriptPath(customerIdn, scriptPath, mapData) {
+        const normalizedScriptPath = this.normalizePathForComparison(scriptPath);
+        for (const [projectIdn, projectData] of Object.entries(mapData.projects)) {
+            for (const [agentIdn, agentData] of Object.entries(projectData.agents)) {
+                for (const [flowIdn, flowData] of Object.entries(agentData.flows)) {
+                    const flowYamlPath = v2FlowYamlPath(customerIdn, projectIdn, agentIdn, flowIdn);
+                    if (!(await fs.pathExists(flowYamlPath))) {
+                        continue;
+                    }
+                    let flowDef;
+                    try {
+                        flowDef = await parseV2FlowYaml(flowYamlPath);
+                    }
+                    catch {
+                        continue;
+                    }
+                    for (const skill of flowDef.skills || []) {
+                        const runnerType = this.normalizeRunnerType(skill.runner_type || flowData.skills[skill.idn]?.runner_type);
+                        const resolvedScriptPath = await this.resolveV2FlowSkillScriptPath(customerIdn, projectIdn, agentIdn, flowIdn, skill.idn, runnerType, skill.prompt_script);
+                        if (this.normalizePathForComparison(resolvedScriptPath) === normalizedScriptPath) {
+                            return {
+                                projectIdn,
+                                agentIdn,
+                                flowIdn,
+                                skillIdn: skill.idn,
+                                skillData: flowData.skills[skill.idn]
+                            };
+                        }
+                    }
+                }
+            }
+        }
+        return null;
+    }
+    resolveV2SkillTargetFromCanonicalPath(scriptPath, mapData) {
+        // Parse canonical V2 path:
+        // .../newo_customers/{cust}/{proj}/agents/{agent}/flows/{flow}/skills/{skillFile}
+        const pathParts = scriptPath.split('/');
+        const skillFileName = pathParts[pathParts.length - 1] || '';
+        const skillIdn = skillFileName.replace(/\.(nsl|nslg|jinja|guidance)$/, '');
+        // skills/ -> flow/ -> flows/ -> agent/ -> agents/ -> project/
+        const flowIdn = pathParts[pathParts.length - 3] || '';
+        const agentIdn = pathParts[pathParts.length - 5] || '';
+        const projectIdn = pathParts[pathParts.length - 7] || '';
+        const projectData = mapData.projects[projectIdn];
+        const agentData = projectData?.agents[agentIdn];
+        const flowData = agentData?.flows[flowIdn];
+        return {
+            projectIdn,
+            agentIdn,
+            flowIdn,
+            skillIdn,
+            skillData: flowData?.skills[skillIdn]
+        };
+    }
     /**
      * Push a V2 library skill update
      * Path: .../newo_customers/{cust}/{proj}/libraries/{lib}/skills/{skillFile}
@@ -686,8 +983,18 @@ export class V2ProjectSyncStrategy {
                     }
                 }
                 for (const [flowIdn, flowData] of Object.entries(agentData.flows)) {
-                    for (const [skillIdn, skillMeta] of Object.entries(flowData.skills)) {
-                        const scriptPath = v2SkillScriptPath(customer.idn, projectIdn, agentIdn, flowIdn, skillIdn, skillMeta.runner_type);
+                    const flowYamlSkills = await this.loadLocalV2FlowSkills(customer.idn, projectIdn, agentIdn, flowIdn);
+                    const skillIdns = new Set([
+                        ...Object.keys(flowData.skills),
+                        ...flowYamlSkills.keys()
+                    ]);
+                    for (const skillIdn of skillIdns) {
+                        const yamlSkill = flowYamlSkills.get(skillIdn);
+                        const skillMeta = flowData.skills[skillIdn];
+                        const runnerType = this.normalizeRunnerType(yamlSkill?.runner_type || skillMeta?.runner_type);
+                        const scriptPath = yamlSkill
+                            ? await this.resolveV2FlowSkillScriptPath(customer.idn, projectIdn, agentIdn, flowIdn, skillIdn, runnerType, yamlSkill.prompt_script)
+                            : v2SkillScriptPath(customer.idn, projectIdn, agentIdn, flowIdn, skillIdn, runnerType);
                         if (await fs.pathExists(scriptPath)) {
                             const content = await fs.readFile(scriptPath, 'utf8');
                             const currentHash = sha256(content);
@@ -726,6 +1033,19 @@ export class V2ProjectSyncStrategy {
         }
         return changes;
     }
+    async loadLocalV2FlowSkills(customerIdn, projectIdn, agentIdn, flowIdn) {
+        const flowYamlPath = v2FlowYamlPath(customerIdn, projectIdn, agentIdn, flowIdn);
+        if (!(await fs.pathExists(flowYamlPath))) {
+            return new Map();
+        }
+        try {
+            const flowDef = await parseV2FlowYaml(flowYamlPath);
+            return new Map((flowDef.skills || []).map(skill => [skill.idn, skill]));
+        }
+        catch {
+            return new Map();
+        }
+    }
     async validate(customer, _items) {
         const errors = [];
         const mapFile = mapPath(customer.idn);
@@ -741,7 +1061,46 @@ export class V2ProjectSyncStrategy {
         for (const [projectIdn, projectData] of Object.entries(mapData.projects)) {
             for (const [agentIdn, agentData] of Object.entries(projectData.agents)) {
                 for (const [flowIdn, flowData] of Object.entries(agentData.flows)) {
+                    const flowYamlPath = v2FlowYamlPath(customer.idn, projectIdn, agentIdn, flowIdn);
+                    let localYamlSkills;
+                    if (await fs.pathExists(flowYamlPath)) {
+                        try {
+                            const flowDef = await parseV2FlowYaml(flowYamlPath);
+                            localYamlSkills = new Map((flowDef.skills || []).map(s => [s.idn, s]));
+                            const skillIdns = new Set([
+                                ...Object.keys(flowData.skills),
+                                ...localYamlSkills.keys()
+                            ]);
+                            for (const skillIdn of skillIdns) {
+                                const localYamlSkill = localYamlSkills.get(skillIdn);
+                                const skillMeta = flowData.skills[skillIdn];
+                                if (!localYamlSkill) {
+                                    errors.push({
+                                        field: `skill.${skillIdn}`,
+                                        message: `Skill exists in project map but is missing from flow YAML: ${flowYamlPath}`,
+                                        path: flowYamlPath
+                                    });
+                                    continue;
+                                }
+                                const runnerType = this.normalizeRunnerType(localYamlSkill.runner_type || skillMeta?.runner_type);
+                                const scriptPath = await this.resolveV2FlowSkillScriptPath(customer.idn, projectIdn, agentIdn, flowIdn, skillIdn, runnerType, localYamlSkill.prompt_script);
+                                if (!(await fs.pathExists(scriptPath))) {
+                                    errors.push({
+                                        field: `skill.${localYamlSkill.idn}`,
+                                        message: `Script file not found: ${scriptPath}`,
+                                        path: scriptPath
+                                    });
+                                }
+                            }
+                        }
+                        catch {
+                            localYamlSkills = undefined;
+                        }
+                    }
                     for (const [skillIdn, skillMeta] of Object.entries(flowData.skills)) {
+                        if (localYamlSkills) {
+                            continue;
+                        }
                         const scriptPath = v2SkillScriptPath(customer.idn, projectIdn, agentIdn, flowIdn, skillIdn, skillMeta.runner_type);
                         if (!(await fs.pathExists(scriptPath))) {
                             errors.push({

package/dist/sandbox/chat.d.ts

@@ -5,9 +5,28 @@
 import type { AxiosInstance } from 'axios';
 import type { SandboxChatSession, Connector, ConversationAct, ChatDebugInfo } from '../types.js';
 /**
- * Find a sandbox connector from the customer's connectors list
+ * Options for selecting which connector to chat through
  */
-export declare function findSandboxConnector(client: AxiosInstance, verbose?: boolean): Promise<Connector | null>;
+export interface ConnectorSelectionOptions {
+    /** Integration IDN to search connectors in (default: 'sandbox') */
+    integrationIdn?: string;
+    /** Exact connector_idn to use; when omitted, the first running connector is used */
+    connectorIdn?: string;
+}
+/**
+ * List running connectors of an integration (default: sandbox).
+ * Used by `newo sandbox --list-connectors` and connector selection.
+ */
+export declare function listRunningSandboxConnectors(client: AxiosInstance, integrationIdn?: string): Promise<Connector[]>;
+/**
+ * Find a sandbox connector from the customer's connectors list.
+ *
+ * Without options, preserves legacy behavior: first running connector of the
+ * 'sandbox' integration. With options.connectorIdn, selects that exact
+ * connector and throws a descriptive error (listing available connectors)
+ * when it is not found or not running.
+ */
+export declare function findSandboxConnector(client: AxiosInstance, verbose?: boolean, options?: ConnectorSelectionOptions): Promise<Connector | null>;
 /**
  * Create a new sandbox chat session
  */
@@ -21,9 +40,10 @@ export declare function sendMessage(client: AxiosInstance, session: SandboxChatS
  * Poll for new conversation acts (messages and debug info)
  * Continues polling until we get an agent response, not just any new message
  */
-export declare function pollForResponse(client: AxiosInstance, session: SandboxChatSession, messageSentAt?: Date | null, verbose?: boolean): Promise<{
+export declare function pollForResponse(client: AxiosInstance, session: SandboxChatSession, messageSentAt?: Date | null, verbose?: boolean, timeoutMs?: number): Promise<{
     acts: ConversationAct[];
     agentPersonaId: string | null;
+    userAct: ConversationAct | null;
 }>;
 /**
  * Extract agent messages from acts