veryfront 0.1.1122 → 0.1.1123

package/esm/src/agent/hosted/cloud-agent-child-tools.js

@@ -0,0 +1,280 @@
+/**
+ * Hosted child tool assembly — MCP server resolution, delegation binding,
+ * invoke-agent tool, and project steering/skill accessors for the cloud agent service.
+ */
+import { createAgentServiceSandboxTools } from "../../sandbox/index.js";
+import { createRemoteMCPToolSource, createToolsFromRemoteDefinitions, isToolVisibleTo, toolRegistry, } from "../../tool/index.js";
+import { SKILL_TOOL_IDS } from "../../skill/types.js";
+import { parseProviderError } from "../../chat/provider-errors.js";
+import { getVeryfrontCloudProviderFromModelId, resolveVeryfrontCloudModelId, resolveVeryfrontCloudModelThinking, resolveVeryfrontCloudReasoningOption, resolveVeryfrontCloudThinkingProviderOptions, } from "../../provider/veryfront-cloud/model-catalog.js";
+import { filterAgentTraceAttributes } from "./trace-attributes.js";
+import { defaultAgentServiceMcpServers, } from "../service/mcp-server-config.js";
+import { resolveRuntimeSkillsForAgent, } from "../runtime/skill-metadata.js";
+import { buildAgentDelegateTools } from "../runtime/agent-delegation.js";
+import { buildVeryfrontCloudRuntimeInstructions } from "./cloud-runtime-system-messages.js";
+import { flattenSystemInstructions } from "../runtime/tool-inventory.js";
+import { createDefaultHostedInvokeAgentTool } from "./default-invoke-agent-tool.js";
+import { fetchDefaultHostedProjectSteering } from "./default-project-steering-refresh.js";
+import { createLiveStudioMcpTools } from "../project/live-studio-mcp-tools.js";
+import { getProjectAgentRuntime, getProjectSteering, resolveAgentConfig, } from "./cloud-agent-config.js";
+const HOSTED_CHILD_LOCAL_SKILL_TOOL_NAMES = new Set([
+    "execute_skill_script",
+    "load_skill_reference",
+]);
+/**
+ * Resolves the effective MCP server list by intersecting service-level options
+ * with optional per-agent overrides.
+ */
+export function resolveMcpServers(options, agentConfig) {
+    if (options.mcpServers !== undefined) {
+        if (agentConfig?.mcpServers === undefined) {
+            return options.mcpServers;
+        }
+        return agentConfig.mcpServers.flatMap((agentServer) => {
+            const hostServer = options.mcpServers?.find((server) => server.kind === agentServer.kind && server.id === agentServer.id);
+            if (!hostServer) {
+                return [];
+            }
+            const toolPolicy = mergeMcpToolPolicies(hostServer.toolPolicy, agentServer.toolPolicy);
+            return [{
+                    ...hostServer,
+                    ...(toolPolicy === undefined ? {} : { toolPolicy }),
+                }];
+        });
+    }
+    if (agentConfig?.mcpServers !== undefined) {
+        return agentConfig.mcpServers;
+    }
+    return defaultAgentServiceMcpServers();
+}
+function mergeMcpToolPolicies(hostPolicy, agentPolicy) {
+    if (hostPolicy === undefined) {
+        return agentPolicy;
+    }
+    if (agentPolicy === undefined) {
+        return hostPolicy;
+    }
+    const allow = hostPolicy.allow === undefined
+        ? agentPolicy.allow
+        : agentPolicy.allow === undefined
+            ? hostPolicy.allow
+            : hostPolicy.allow.filter((toolName) => agentPolicy.allow?.includes(toolName));
+    const deny = [
+        ...new Set([
+            ...(hostPolicy.deny ?? []),
+            ...(agentPolicy.deny ?? []),
+        ]),
+    ];
+    const approval = hostPolicy.approval ?? agentPolicy.approval;
+    return {
+        ...(allow === undefined ? {} : { allow }),
+        ...(deny.length === 0 ? {} : { deny }),
+        ...(approval === undefined ? {} : { approval }),
+    };
+}
+/**
+ * Returns the set of host tools visible to the given agent scope, excluding
+ * shared skill infrastructure tools (load_skill_reference, execute_skill_script).
+ */
+export function getDiscoveredHostTools(scope) {
+    // Without an agent identity, this remains the project-level host tool spread
+    // and matches MCP tools/list: project-level callers see only unowned tools.
+    // Hosted per-agent runs pass their task context identity so owned colocated
+    // tools are available to their owner and hidden from other agents.
+    // Shared skill tools use local registry and filesystem state. Hosted runs
+    // instead add the request-scoped load_skill tool below; its optional file
+    // input reads references with project, branch, auth, and owner context.
+    // Hosted runs do not execute skill scripts directly.
+    return Object.fromEntries([...toolRegistry.getAll()]
+        .filter(([toolId, registryTool]) => !SKILL_TOOL_IDS.has(toolId) && isToolVisibleTo(registryTool, scope))
+        .sort(([left], [right]) => left.localeCompare(right)));
+}
+/** Fetches the project instructions for the given agent id and lookup context. */
+export function getProjectInstructions(context, lookup, agentId) {
+    return context.trace("chat.getProjectInstructions", async () => {
+        return await getProjectSteering(context, agentId).getProjectInstructions(lookup);
+    });
+}
+/** Fetches the resolved skill definitions for the given agent id and lookup context. */
+export function getSkillsConfig(context, lookup, agentId) {
+    return context.trace("chat.getSkillsConfig", async () => {
+        return await getProjectSteering(context, agentId).getSkillsConfig(lookup);
+    });
+}
+/** Creates the load_skill tool scoped to the given tool context. */
+export function createLoadSkillTool(context, toolContext) {
+    return getProjectSteering(context, toolContext.agentId).createLoadSkillTool(toolContext);
+}
+/** Refreshes the project skill ids for the given skill context. */
+export async function refreshProjectSkillIds(context, skillContext) {
+    await getProjectSteering(context, skillContext.agentId).refreshProjectSkillIds(skillContext);
+}
+/** Sets filtered trace attributes on the active span. */
+export function setFilteredTraceAttributes(context, attributes) {
+    context.infrastructure.setActiveSpanAttributes(filterAgentTraceAttributes(attributes));
+}
+function getInvokeAgentConfig(context) {
+    const config = context.infrastructure.getConfig();
+    return {
+        apiUrl: config.VERYFRONT_API_URL,
+        apiMcpUrl: config.VERYFRONT_MCP_URL,
+        studioMcpUrl: config.VERYFRONT_STUDIO_MCP_URL,
+        mcpServers: resolveMcpServers(context.options),
+        enableDurableInvokeAgent: config.VERYFRONT_ENABLE_DURABLE_INVOKE_AGENT,
+    };
+}
+function shouldRethrowInvokeAgentError(error) {
+    return parseProviderError(error).code === "INSUFFICIENT_CREDITS";
+}
+/** Resolves the effective tool name allowlist for a hosted child agent run. */
+export function resolveHostedChildToolNames(agentConfig) {
+    if (agentConfig.tools === true) {
+        return undefined;
+    }
+    return [
+        ...new Set([
+            ...(agentConfig.tools ?? []).filter((toolName) => !HOSTED_CHILD_LOCAL_SKILL_TOOL_NAMES.has(toolName)),
+            ...(agentConfig.providerTools ?? []),
+            ...(agentConfig.delegates ?? []).map((id) => `agent_${id}`),
+            "load_skill",
+        ]),
+    ];
+}
+/** Builds the child run context for a nested hosted agent invocation. */
+export function buildHostedChildToolContext(globalToolContext, childAgentId, childConfig, durableChildRun) {
+    return {
+        ...globalToolContext,
+        agentId: childAgentId,
+        ...(childConfig?.availableSkillIds ? { availableSkillIds: childConfig.availableSkillIds } : {}),
+        ...(childConfig?.skillSourcePaths ? { skillSourcePaths: childConfig.skillSourcePaths } : {}),
+        ...(childConfig?.toolNames ? { availableToolNames: childConfig.toolNames } : {}),
+        loadedSkillResponses: {},
+        loadedSkillReferenceResponses: {},
+        ...(durableChildRun
+            ? {
+                conversationId: durableChildRun.childConversationId,
+                parentRunId: durableChildRun.childRunId,
+                parentMessageId: durableChildRun.childMessageId,
+            }
+            : {}),
+    };
+}
+/** Fetches project steering for a given project / auth / branch combination. */
+export function fetchProjectSteering(context, input, agentId) {
+    return fetchDefaultHostedProjectSteering({
+        ...input,
+        fetchProjectInstructions: (lookup) => getProjectInstructions(context, lookup, agentId),
+        fetchSkills: (lookup) => getSkillsConfig(context, lookup, agentId),
+        trace: context.trace,
+        traceOperationName: "chat.fetchSteering",
+    });
+}
+/** Resolves the execution config for a hosted child agent invocation. */
+export async function resolveHostedChildAgentExecutionConfig(context, taskContext, childAgentId, projectId) {
+    if (!getProjectAgentRuntime(context).agents.has(childAgentId)) {
+        return undefined;
+    }
+    const agentConfig = await resolveAgentConfig(context, childAgentId);
+    const branchId = projectId === taskContext.projectId ? taskContext.branchId : null;
+    const steering = await fetchProjectSteering(context, {
+        projectId: projectId || null,
+        authToken: taskContext.authToken,
+        branchId,
+    }, childAgentId);
+    const advertisedSkills = resolveRuntimeSkillsForAgent({
+        skills: steering.skills,
+        agentId: childAgentId,
+        selector: agentConfig.skills,
+    });
+    const loadableSkills = resolveRuntimeSkillsForAgent({
+        skills: steering.skills,
+        agentId: childAgentId,
+        selector: true,
+    });
+    const skillSourcePaths = Object.fromEntries(loadableSkills
+        .filter((skill) => skill.sourcePath)
+        .map((skill) => [skill.id, skill.sourcePath]));
+    const toolNames = resolveHostedChildToolNames(agentConfig);
+    const thinking = agentConfig.thinking?.enabled === false ? 0 : agentConfig.thinking?.budgetTokens;
+    return {
+        system: flattenSystemInstructions(buildVeryfrontCloudRuntimeInstructions({
+            agentConfig,
+            projectId: projectId || null,
+            branchId,
+            instructions: steering.instructions,
+            skills: advertisedSkills,
+            availableToolNames: toolNames,
+        })),
+        ...(agentConfig.model ? { model: agentConfig.model } : {}),
+        ...(agentConfig.temperature === undefined ? {} : { temperature: agentConfig.temperature }),
+        ...(agentConfig.maxSteps === undefined ? {} : { maxSteps: agentConfig.maxSteps }),
+        ...(thinking === undefined ? {} : { thinking }),
+        ...(toolNames === undefined ? {} : { toolNames }),
+        mcpServers: resolveMcpServers(context.options, agentConfig),
+        availableSkillIds: loadableSkills.map((skill) => skill.id),
+        ...(Object.keys(skillSourcePaths).length > 0 ? { skillSourcePaths } : {}),
+        ...(agentConfig.delegates === undefined ? {} : { delegateIds: agentConfig.delegates }),
+    };
+}
+/** Creates the invoke_agent tool for the given child context. */
+export function createInvokeAgentTool(context, childContext, options) {
+    return createDefaultHostedInvokeAgentTool({
+        context: childContext,
+        getConfig: () => getInvokeAgentConfig(context),
+        logger: context.infrastructure.logger,
+        trace: context.trace,
+        setTraceAttributes: context.infrastructure.setActiveSpanAttributes,
+        createBashTool: context.options.createBashTool,
+        resolveModelId: resolveVeryfrontCloudModelId,
+        resolveProvider: getVeryfrontCloudProviderFromModelId,
+        resolveModelThinking: resolveVeryfrontCloudModelThinking,
+        resolveProviderOptions: resolveVeryfrontCloudThinkingProviderOptions,
+        resolveReasoning: resolveVeryfrontCloudReasoningOption,
+        shouldRethrowError: shouldRethrowInvokeAgentError,
+        buildGlobalTools: (globalToolContext, childAgentId, childConfig, durableChildRun) => {
+            const childToolContext = buildHostedChildToolContext(globalToolContext, childAgentId, childConfig, durableChildRun);
+            return {
+                ...(childConfig ? getDiscoveredHostTools({ agentId: childAgentId }) : {}),
+                load_skill: createLoadSkillTool(context, childToolContext),
+                ...(childConfig?.delegateIds?.length
+                    ? buildHostedDelegateTools(context, {
+                        delegates: childConfig.delegateIds,
+                        selfId: childAgentId,
+                        taskContext: childToolContext,
+                    })
+                    : {}),
+            };
+        },
+        resolveChildAgentExecutionConfig: (childAgentId, projectId) => resolveHostedChildAgentExecutionConfig(context, childContext, childAgentId, projectId),
+        refreshProjectSkillIds: (projectSkillContext) => refreshProjectSkillIds(context, projectSkillContext),
+        createAgentServiceSandboxTools,
+        createLiveStudioTools: createLiveStudioMcpTools,
+        createRemoteToolSource: createRemoteMCPToolSource,
+        createToolsFromRemoteDefinitions,
+        requireDurableInvokeAgent: options?.requireDurable,
+    });
+}
+/** Builds the set of delegate agent tools for the given delegate ids. */
+export function buildHostedDelegateTools(context, input) {
+    const invokeAgent = createInvokeAgentTool(context, input.taskContext, { requireDurable: true });
+    return buildAgentDelegateTools({
+        delegates: input.delegates,
+        selfId: input.selfId,
+        resolveAgent: (delegateId) => getProjectAgentRuntime(context).agents.get(delegateId),
+        executeDelegate: ({ delegateId, toolInput, context: executionContext }) => invokeAgent.execute({
+            agent_id: delegateId,
+            description: `Run ${delegateId} specialist task`,
+            prompt: toolInput.input,
+        }, executionContext),
+    });
+}
+/**
+ * Resolves the delegation binding from an agent config. Agents with an explicit
+ * `delegates` list use scoped delegation; all others fall back to legacy invoke_agent.
+ */
+export function resolveHostedDelegationBinding(agentConfig) {
+    if (agentConfig?.delegates !== undefined) {
+        return { kind: "scoped", delegateIds: agentConfig.delegates };
+    }
+    return { kind: "legacy" };
+}

package/esm/src/agent/hosted/cloud-agent-config.d.ts

@@ -0,0 +1,69 @@
+import type { AgUiResumeValue } from "../ag-ui/tool-shared.js";
+import { type HostedAgentProjectSteering } from "./agent-project-steering.js";
+import { type ProjectAgentRuntimeDiscovery } from "../project/agent-runtime.js";
+import type { RuntimeAgentMarkdownDefinition } from "../runtime/agent-definition.js";
+import type { ResolvedNodeVeryfrontCloudAgentServiceOptions } from "./cloud-agent-provider-bootstrap.js";
+/**
+ * Full runtime context for a running cloud agent service instance.
+ * Typed as the return of its creator so accessors can use the inferred shape.
+ */
+export type NodeVeryfrontCloudAgentServiceContext = ReturnType<typeof createNodeVeryfrontCloudAgentServiceContext>;
+/** Creates the shared runtime context for a cloud agent service instance. */
+export declare function createNodeVeryfrontCloudAgentServiceContext(options: ResolvedNodeVeryfrontCloudAgentServiceOptions): {
+    options: ResolvedNodeVeryfrontCloudAgentServiceOptions;
+    processTarget: NodeJS.Process | (import("../../extensions/observability/node-telemetry-provider.js").NodeTelemetryProcessTarget & import("../index.js").AbortRejectionProcessTarget & {
+        env?: import("../index.js").CreateNodeAgentServiceRuntimeInfrastructureOptions["env"];
+        exit?: (code: number) => never | void;
+    }) | undefined;
+    projectDir: string;
+    infrastructure: import("../index.js").NodeAgentServiceRuntimeInfrastructure;
+    trace: {
+        <TResult>(operationName: string, operation: () => Promise<TResult>): Promise<TResult>;
+        <TResult>(operationName: string, operation: () => TResult): TResult;
+    };
+    defaultAgentId: string | null;
+    projectSteeringByAgentId: Map<string, HostedAgentProjectSteering>;
+    tracker: import("../index.js").DetachedRunTracker<AgUiResumeValue>;
+    discoveryResult: ProjectAgentRuntimeDiscovery | null;
+    agentConfig: RuntimeAgentMarkdownDefinition | null;
+    agentConfigs: Map<string, import("../../extensions/schema/schema-validator.js").InferShape<{
+        id: import("../../internal-agents/schema.js").Schema<string>;
+        name: import("../../internal-agents/schema.js").Schema<string>;
+        description: import("../../internal-agents/schema.js").Schema<string>;
+        avatarUrl: import("../../internal-agents/schema.js").Schema<string | undefined>;
+        instructions: import("../../internal-agents/schema.js").Schema<string>;
+        thinking: import("../../internal-agents/schema.js").Schema<import("../../extensions/schema/schema-validator.js").InferShape<{
+            enabled: import("../../internal-agents/schema.js").Schema<boolean>;
+            budgetTokens: import("../../internal-agents/schema.js").Schema<number | undefined>;
+        }> | undefined>;
+        model: import("../../internal-agents/schema.js").Schema<string | undefined>;
+        temperature: import("../../internal-agents/schema.js").Schema<number | undefined>;
+        maxSteps: import("../../internal-agents/schema.js").Schema<number | undefined>;
+        providerTools: import("../../internal-agents/schema.js").Schema<string[] | undefined>;
+        skills: import("../../internal-agents/schema.js").Schema<boolean | string[] | undefined>;
+        tools: import("../../internal-agents/schema.js").Schema<true | string[] | undefined>;
+        delegates: import("../../internal-agents/schema.js").Schema<string[] | undefined>;
+        mcpServers: import("../../internal-agents/schema.js").Schema<import("../../extensions/schema/schema-validator.js").InferShape<{
+            kind: import("../../internal-agents/schema.js").Schema<"veryfront-api" | "veryfront-studio">;
+            id: import("../../internal-agents/schema.js").Schema<string | undefined>;
+            toolPolicy: import("../../internal-agents/schema.js").Schema<import("../../extensions/schema/schema-validator.js").InferShape<{
+                allow: import("../../internal-agents/schema.js").Schema<string[] | undefined>;
+                deny: import("../../internal-agents/schema.js").Schema<string[] | undefined>;
+                approval: import("../../internal-agents/schema.js").Schema<"never" | undefined>;
+            }> | undefined>;
+        }>[] | undefined>;
+    }>>;
+};
+/** Resolves and caches the agent config for the given agent id. */
+export declare function resolveAgentConfig(context: NodeVeryfrontCloudAgentServiceContext, agentId: string): Promise<RuntimeAgentMarkdownDefinition>;
+/** Returns the resolved agent config, throwing if the context has not been initialized. */
+export declare function getResolvedAgentConfig(context: NodeVeryfrontCloudAgentServiceContext): RuntimeAgentMarkdownDefinition;
+/** Returns the discovered project agent runtime, throwing if not yet initialized. */
+export declare function getProjectAgentRuntime(context: NodeVeryfrontCloudAgentServiceContext): ProjectAgentRuntimeDiscovery;
+/** Discovers project primitives and resolves the default agent id and config. */
+export declare function initializeNodeVeryfrontCloudAgentServiceContext(context: NodeVeryfrontCloudAgentServiceContext): Promise<void>;
+/** Returns the default agent id, throwing if the context has not been initialized. */
+export declare function getDefaultAgentId(context: NodeVeryfrontCloudAgentServiceContext): string;
+/** Returns (and caches) the project steering object for the given agent id. */
+export declare function getProjectSteering(context: NodeVeryfrontCloudAgentServiceContext, agentId?: string): HostedAgentProjectSteering;
+//# sourceMappingURL=cloud-agent-config.d.ts.map

package/esm/src/agent/hosted/cloud-agent-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cloud-agent-config.d.ts","sourceRoot":"","sources":["../../../../src/src/agent/hosted/cloud-agent-config.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAC/D,OAAO,EAEL,KAAK,0BAA0B,EAChC,MAAM,6BAA6B,CAAC;AACrC,OAAO,EAML,KAAK,4BAA4B,EAElC,MAAM,6BAA6B,CAAC;AACrC,OAAO,KAAK,EAAE,8BAA8B,EAAE,MAAM,gCAAgC,CAAC;AAErF,OAAO,KAAK,EAAE,6CAA6C,EAAE,MAAM,qCAAqC,CAAC;AAQzG;;;GAGG;AACH,MAAM,MAAM,qCAAqC,GAAG,UAAU,CAC5D,OAAO,2CAA2C,CACnD,CAAC;AAEF,6EAA6E;AAC7E,wBAAgB,2CAA2C,CACzD,OAAO,EAAE,6CAA6C;;;;;;;;;SAQvC,OAAO,iBACL,MAAM,aACV,MAAM,OAAO,CAAC,OAAO,CAAC,GAChC,OAAO,CAAC,OAAO,CAAC;SACJ,OAAO,iBAAiB,MAAM,aAAa,MAAM,OAAO,GAAG,OAAO;;oBAcvD,MAAM,GAAG,IAAI;;;qBAGZ,4BAA4B,GAAG,IAAI;iBACvC,8BAA8B,GAAG,IAAI;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAG7D;AAgBD,mEAAmE;AACnE,wBAAsB,kBAAkB,CACtC,OAAO,EAAE,qCAAqC,EAC9C,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,8BAA8B,CAAC,CAsBzC;AAED,2FAA2F;AAC3F,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,qCAAqC,GAC7C,8BAA8B,CAOhC;AAED,qFAAqF;AACrF,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,qCAAqC,GAC7C,4BAA4B,CAK9B;AAgCD,iFAAiF;AACjF,wBAAsB,+CAA+C,CACnE,OAAO,EAAE,qCAAqC,GAC7C,OAAO,CAAC,IAAI,CAAC,CAIf;AAED,sFAAsF;AACtF,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,qCAAqC,GAAG,MAAM,CAQxF;AAED,+EAA+E;AAC/E,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,qCAAqC,EAC9C,OAAO,GAAE,MAAmC,GAC3C,0BAA0B,CAgB5B"}

package/esm/src/agent/hosted/cloud-agent-config.js

@@ -0,0 +1,129 @@
+/** Agent-config resolution, context creation, and project-steering accessor for the cloud agent service. */
+import { AGENT_NOT_FOUND, CONFIG_INVALID, INITIALIZATION_ERROR } from "../../errors/index.js";
+import { createNodeAgentServiceRuntimeInfrastructure } from "../service/node-runtime-infrastructure.js";
+import { createDetachedRunTracker } from "../service/detached-run-tracker.js";
+import { createHostedAgentProjectSteering, } from "./agent-project-steering.js";
+import { createRuntimeAgentDefinitionFromAgent, describeProjectAgentRuntimeAgentIdCandidates, discoverProjectAgentRuntime, doesProjectAgentRuntimeAgentMatchSource, getProjectAgentRuntimeAgentIdCandidates, resolveSingleProjectAgentRuntimeAgentId, } from "../project/agent-runtime.js";
+import { nodeAdapter } from "../../platform/adapters/node.js";
+import { resolveBaseDir, resolveDefaultProcessTarget, resolveEnvironment, resolveProjectDir, } from "./cloud-agent-paths.js";
+/** Creates the shared runtime context for a cloud agent service instance. */
+export function createNodeVeryfrontCloudAgentServiceContext(options) {
+    const processTarget = options.processTarget ?? resolveDefaultProcessTarget();
+    const infrastructure = createNodeAgentServiceRuntimeInfrastructure({
+        serviceName: options.serviceName,
+        env: resolveEnvironment({ env: options.env, processTarget }),
+        processTarget,
+    });
+    function trace(operationName, operation) {
+        return infrastructure.tracer.trace(operationName, operation);
+    }
+    return {
+        options,
+        processTarget,
+        projectDir: resolveProjectDir(options),
+        infrastructure,
+        trace,
+        defaultAgentId: null,
+        projectSteeringByAgentId: new Map(),
+        tracker: createDetachedRunTracker(),
+        discoveryResult: null,
+        agentConfig: null,
+        agentConfigs: new Map(),
+    };
+}
+function getMarkdownAgentConfig(context, agentId) {
+    return getProjectSteering(context, agentId).getAgentConfig();
+}
+function loadMarkdownAgentConfig(context, agentId) {
+    return getMarkdownAgentConfig(context, agentId);
+}
+/** Resolves and caches the agent config for the given agent id. */
+export async function resolveAgentConfig(context, agentId) {
+    const cachedAgentConfig = context.agentConfigs.get(agentId);
+    if (cachedAgentConfig) {
+        return cachedAgentConfig;
+    }
+    const source = context.options.agentSource ?? "auto";
+    const codeAgent = getProjectAgentRuntime(context).agents.get(agentId);
+    if (codeAgent && doesProjectAgentRuntimeAgentMatchSource(codeAgent, source)) {
+        const agentConfig = await createRuntimeAgentDefinitionFromAgent(codeAgent);
+        context.agentConfigs.set(agentConfig.id, agentConfig);
+        return agentConfig;
+    }
+    if (source === "code") {
+        throw AGENT_NOT_FOUND.create({ detail: `Code agent "${agentId}" was not discovered.` });
+    }
+    const agentConfig = loadMarkdownAgentConfig(context, agentId);
+    context.agentConfigs.set(agentConfig.id, agentConfig);
+    return agentConfig;
+}
+/** Returns the resolved agent config, throwing if the context has not been initialized. */
+export function getResolvedAgentConfig(context) {
+    if (!context.agentConfig) {
+        throw INITIALIZATION_ERROR.create({
+            detail: "Agent service context has not been initialized.",
+        });
+    }
+    return context.agentConfig;
+}
+/** Returns the discovered project agent runtime, throwing if not yet initialized. */
+export function getProjectAgentRuntime(context) {
+    if (!context.discoveryResult) {
+        throw new Error("Agent service context has not been initialized.");
+    }
+    return context.discoveryResult;
+}
+async function discoverProjectPrimitives(context) {
+    context.discoveryResult = await discoverProjectAgentRuntime({
+        projectDir: context.projectDir,
+        adapter: nodeAdapter,
+    });
+}
+function resolveDefaultAgentId(context) {
+    if (context.options.agentId) {
+        return context.options.agentId;
+    }
+    const source = context.options.agentSource ?? "auto";
+    const candidates = getProjectAgentRuntimeAgentIdCandidates(context.discoveryResult);
+    const agentId = resolveSingleProjectAgentRuntimeAgentId({ candidates, source });
+    if (agentId) {
+        return agentId;
+    }
+    throw CONFIG_INVALID.create({
+        detail: [
+            "agentId is required when agent discovery does not resolve to exactly one agent.",
+            `Discovered agents: ${describeProjectAgentRuntimeAgentIdCandidates(candidates)}.`,
+        ].join(" "),
+    });
+}
+/** Discovers project primitives and resolves the default agent id and config. */
+export async function initializeNodeVeryfrontCloudAgentServiceContext(context) {
+    await discoverProjectPrimitives(context);
+    context.defaultAgentId = resolveDefaultAgentId(context);
+    context.agentConfig = await resolveAgentConfig(context, context.defaultAgentId);
+}
+/** Returns the default agent id, throwing if the context has not been initialized. */
+export function getDefaultAgentId(context) {
+    if (!context.defaultAgentId) {
+        throw INITIALIZATION_ERROR.create({
+            detail: "Agent service context has not been initialized.",
+        });
+    }
+    return context.defaultAgentId;
+}
+/** Returns (and caches) the project steering object for the given agent id. */
+export function getProjectSteering(context, agentId = getDefaultAgentId(context)) {
+    const cachedProjectSteering = context.projectSteeringByAgentId.get(agentId);
+    if (cachedProjectSteering) {
+        return cachedProjectSteering;
+    }
+    const projectSteering = createHostedAgentProjectSteering({
+        baseDir: resolveBaseDir(context.options),
+        agentId,
+        getApiUrl: () => context.infrastructure.getConfig().VERYFRONT_API_URL,
+        logger: context.infrastructure.logger,
+        trace: context.trace,
+    });
+    context.projectSteeringByAgentId.set(agentId, projectSteering);
+    return projectSteering;
+}

package/esm/src/agent/hosted/cloud-agent-paths.d.ts

@@ -0,0 +1,42 @@
+import type { CreateNodeAgentServiceRuntimeInfrastructureOptions } from "../service/node-runtime-infrastructure.js";
+/** A path option that is either a string path or a URL. */
+export type AgentServicePathOption = string | URL;
+export declare const DEFAULT_AGENT_SERVICE_NAME = "veryfront-agent-service";
+/** Converts a path option (string or URL) to a string path. */
+export declare function pathOptionToPath(pathOption: AgentServicePathOption): string;
+/** Resolves the base directory from baseDir or entrypointUrl options. */
+export declare function resolveBaseDir(options: {
+    baseDir?: AgentServicePathOption;
+    entrypointUrl?: AgentServicePathOption;
+}): string;
+/** Resolves the project directory from options, walking up for a discovery root. */
+export declare function resolveProjectDir(options: {
+    baseDir?: AgentServicePathOption;
+    entrypointUrl?: AgentServicePathOption;
+    projectDir?: string;
+}): string;
+/** Reads the `name` field from the nearest package.json or deno.json, or null. */
+export declare function readProjectManifestName(projectDir: string): string | null;
+type ServiceNameOptions = {
+    serviceName?: string;
+    baseDir?: AgentServicePathOption;
+    entrypointUrl?: AgentServicePathOption;
+    projectDir?: string;
+    env?: CreateNodeAgentServiceRuntimeInfrastructureOptions["env"];
+    processTarget?: {
+        env?: CreateNodeAgentServiceRuntimeInfrastructureOptions["env"];
+    };
+};
+/** Resolves the service name from options, env, or project manifest. */
+export declare function resolveServiceName(options: ServiceNameOptions): string;
+/** Returns the default process target if `process` is available in the runtime. */
+export declare function resolveDefaultProcessTarget(): NodeJS.Process | undefined;
+/** Resolves the environment record from explicit env, processTarget.env, or the process env. */
+export declare function resolveEnvironment(options: {
+    env?: CreateNodeAgentServiceRuntimeInfrastructureOptions["env"];
+    processTarget?: {
+        env?: CreateNodeAgentServiceRuntimeInfrastructureOptions["env"];
+    };
+}): CreateNodeAgentServiceRuntimeInfrastructureOptions["env"];
+export {};
+//# sourceMappingURL=cloud-agent-paths.d.ts.map

package/esm/src/agent/hosted/cloud-agent-paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cloud-agent-paths.d.ts","sourceRoot":"","sources":["../../../../src/src/agent/hosted/cloud-agent-paths.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,kDAAkD,EAAE,MAAM,2CAA2C,CAAC;AAEpH,2DAA2D;AAC3D,MAAM,MAAM,sBAAsB,GAAG,MAAM,GAAG,GAAG,CAAC;AAElD,eAAO,MAAM,0BAA0B,4BAA4B,CAAC;AAQpE,+DAA+D;AAC/D,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,sBAAsB,GAAG,MAAM,CAE3E;AAED,yEAAyE;AACzE,wBAAgB,cAAc,CAC5B,OAAO,EAAE;IAAE,OAAO,CAAC,EAAE,sBAAsB,CAAC;IAAC,aAAa,CAAC,EAAE,sBAAsB,CAAA;CAAE,GACpF,MAAM,CAQR;AAqBD,oFAAoF;AACpF,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE;IACP,OAAO,CAAC,EAAE,sBAAsB,CAAC;IACjC,aAAa,CAAC,EAAE,sBAAsB,CAAC;IACvC,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,GACA,MAAM,CAQR;AAgBD,kFAAkF;AAClF,wBAAgB,uBAAuB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAsBzE;AAED,KAAK,kBAAkB,GAAG;IACxB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,sBAAsB,CAAC;IACjC,aAAa,CAAC,EAAE,sBAAsB,CAAC;IACvC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,GAAG,CAAC,EAAE,kDAAkD,CAAC,KAAK,CAAC,CAAC;IAChE,aAAa,CAAC,EAAE;QAAE,GAAG,CAAC,EAAE,kDAAkD,CAAC,KAAK,CAAC,CAAA;KAAE,CAAC;CACrF,CAAC;AAEF,wEAAwE;AACxE,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,kBAAkB,GAAG,MAAM,CAYtE;AAED,mFAAmF;AACnF,wBAAgB,2BAA2B,+BAK1C;AAED,gGAAgG;AAChG,wBAAgB,kBAAkB,CAChC,OAAO,EAAE;IACP,GAAG,CAAC,EAAE,kDAAkD,CAAC,KAAK,CAAC,CAAC;IAChE,aAAa,CAAC,EAAE;QAAE,GAAG,CAAC,EAAE,kDAAkD,CAAC,KAAK,CAAC,CAAA;KAAE,CAAC;CACrF,GACA,kDAAkD,CAAC,KAAK,CAAC,CAQ3D"}

package/esm/src/agent/hosted/cloud-agent-paths.js

@@ -0,0 +1,117 @@
+/** Path and directory resolution utilities for the Veryfront Cloud agent service. */
+import { existsSync, readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, resolve } from "../../platform/compat/path/index.js";
+import { cwd, env } from "../../platform/compat/process.js";
+import { defineSchema } from "../../schemas/index.js";
+import { DEFAULT_PROJECT_DISCOVERY_DIRS } from "../../discovery/index.js";
+export const DEFAULT_AGENT_SERVICE_NAME = "veryfront-agent-service";
+const PROJECT_CONFIG_FILES = [
+    "veryfront.config.js",
+    "veryfront.config.ts",
+    "veryfront.config.mjs",
+];
+/** Converts a path option (string or URL) to a string path. */
+export function pathOptionToPath(pathOption) {
+    return pathOption instanceof URL ? fileURLToPath(pathOption) : pathOption;
+}
+/** Resolves the base directory from baseDir or entrypointUrl options. */
+export function resolveBaseDir(options) {
+    if (options.baseDir !== undefined) {
+        return pathOptionToPath(options.baseDir);
+    }
+    if (options.entrypointUrl !== undefined) {
+        return dirname(pathOptionToPath(options.entrypointUrl));
+    }
+    return cwd();
+}
+function hasDiscoveryRoot(baseDir) {
+    const discoveryDirs = [
+        ...DEFAULT_PROJECT_DISCOVERY_DIRS.agentDirs,
+        ...DEFAULT_PROJECT_DISCOVERY_DIRS.toolDirs,
+        ...DEFAULT_PROJECT_DISCOVERY_DIRS.skillDirs,
+        ...DEFAULT_PROJECT_DISCOVERY_DIRS.resourceDirs,
+        ...DEFAULT_PROJECT_DISCOVERY_DIRS.promptDirs,
+        ...DEFAULT_PROJECT_DISCOVERY_DIRS.workflowDirs,
+        ...DEFAULT_PROJECT_DISCOVERY_DIRS.taskDirs,
+    ];
+    return discoveryDirs.some((dir) => existsSync(resolve(baseDir, dir))) ||
+        PROJECT_CONFIG_FILES.some((file) => existsSync(resolve(baseDir, file)));
+}
+function uniquePaths(paths) {
+    return [...new Set(paths.map((path) => resolve(path)))];
+}
+/** Resolves the project directory from options, walking up for a discovery root. */
+export function resolveProjectDir(options) {
+    if (options.projectDir) {
+        return options.projectDir;
+    }
+    const baseDir = resolveBaseDir(options);
+    const candidates = uniquePaths([baseDir, dirname(baseDir), dirname(dirname(baseDir))]);
+    return candidates.find(hasDiscoveryRoot) ?? baseDir;
+}
+/**
+ * Schema for the subset of a project manifest (package.json / deno.json) we
+ * read. Only `name` is consumed; extra fields are tolerated via passthrough so
+ * arbitrary manifests validate. Defined lazily via `defineSchema` so the zod
+ * extension is resolved at call time — the cloud-agent options resolver calls
+ * `ensureDefaultSchemaValidator()` before reaching service-name resolution, so
+ * a validator is registered by the time this runs.
+ */
+const getProjectManifestSchema = defineSchema((v) => v.object({
+    name: v.string().optional(),
+}).passthrough());
+/** Reads the `name` field from the nearest package.json or deno.json, or null. */
+export function readProjectManifestName(projectDir) {
+    const manifestSchema = getProjectManifestSchema();
+    for (const fileName of ["package.json", "deno.json"]) {
+        const filePath = resolve(projectDir, fileName);
+        if (!existsSync(filePath)) {
+            continue;
+        }
+        try {
+            const result = manifestSchema.safeParse(JSON.parse(readFileSync(filePath, "utf8")));
+            if (!result.success)
+                continue;
+            const name = result.data.name;
+            if (typeof name !== "string")
+                continue;
+            const trimmedName = name.trim();
+            if (trimmedName)
+                return trimmedName;
+        }
+        catch {
+            continue;
+        }
+    }
+    return null;
+}
+/** Resolves the service name from options, env, or project manifest. */
+export function resolveServiceName(options) {
+    if (options.serviceName?.trim()) {
+        return options.serviceName.trim();
+    }
+    const resolved = resolveEnvironment(options);
+    const envServiceName = resolved?.VERYFRONT_AGENT_SERVICE_NAME?.trim();
+    if (envServiceName) {
+        return envServiceName;
+    }
+    return readProjectManifestName(resolveProjectDir(options)) ?? DEFAULT_AGENT_SERVICE_NAME;
+}
+/** Returns the default process target if `process` is available in the runtime. */
+export function resolveDefaultProcessTarget() {
+    if (typeof process === "undefined") {
+        return undefined;
+    }
+    return process;
+}
+/** Resolves the environment record from explicit env, processTarget.env, or the process env. */
+export function resolveEnvironment(options) {
+    if (options.env) {
+        return options.env;
+    }
+    if (options.processTarget?.env) {
+        return options.processTarget.env;
+    }
+    return env();
+}