@owlmeans/viable-sdk 0.1.18-rc.1

package/build/tools/refusal.js

@@ -0,0 +1,377 @@
+import { ResilientError } from '@owlmeans/error';
+import { ModerationCategory } from '@owlmeans/viable-common';
+/** What each moderation category refused, in the words the refusal is explained with. */
+const MODERATION = {
+    [ModerationCategory.CredentialHarvesting]: 'collecting other people\'s passwords, one-time codes or card details',
+    [ModerationCategory.BrandImpersonation]: 'presenting itself as another company or as a real person',
+    [ModerationCategory.PaymentCapture]: 'taking payment details on behalf of a merchant the requester does not run',
+    [ModerationCategory.AbuseTooling]: 'abuse — unsolicited bulk messaging, credential stuffing or phishing kits',
+};
+/** ` (detail)`, or nothing at all: a phrase must read as a sentence when there is no detail. */
+const aside = (detail) => detail !== '' ? ` (${detail})` : '';
+/**
+ * Every refusal a connector can be handed, and the one sentence it is handed instead.
+ *
+ * Ordered by SPECIFICITY, because the first marker the message contains wins: every reason of a
+ * family sits above the family's own marker, or the family would answer for all of them. A marker
+ * that is a substring of a later one is a marker that shadows it, which `catalogue.spec.ts` pins
+ * rather than leaves to review.
+ *
+ * The markers are literals here on purpose. They are wire text owned by packages this one does not
+ * depend on, and copying the constant would need a dependency edge from a tooling package onto the
+ * platform's own — so they are spelled once, in the order the platform spells them, and are
+ * exactly the substrings the manager's own phrasing matches on. Anything unmatched falls back to
+ * its marker, which is the one outcome that stays honest as the platform grows a refusal this
+ * table has never heard of.
+ */
+export const REFUSALS = [
+    // ── A conversion refused by the platform ────────────────────────────────────────────────────
+    {
+        marker: 'conversion:unsupported:monorepo',
+        phrase: paths => 'This repository points at code that is not inside it — a git submodule, or a'
+            + ' workspace package that lives elsewhere. Converting needs everything in one repository.'
+            + (paths !== '' ? `\nunlinked: ${paths}` : ''),
+    },
+    {
+        marker: 'conversion:unsupported:bad-origin-url',
+        phrase: url => 'That is not a repository address the platform can clone. Give the repository\'s'
+            + ' own address, in the form https://github.com/owner/repository.'
+            + (url !== '' ? `\ngiven: ${url}` : ''),
+    },
+    {
+        marker: 'conversion:unsupported:not-linked',
+        phrase: () => 'The platform has no way to read that repository: no GitHub connection is'
+            + ' recorded for this project, or its access was revoked. The user connects it in the web'
+            + ' application, and the conversion is started again afterwards.',
+    },
+    {
+        marker: 'conversion:unsupported:no-origin',
+        phrase: () => 'This project was generated by the platform rather than imported, so there is'
+            + ' nothing to convert. develop_story is what changes a generated project.',
+    },
+    {
+        marker: 'conversion:unsupported:not-convertible',
+        phrase: () => 'The intake refused this origin: a conversion needs an application with source'
+            + ' code it can read, not an empty repository, a documentation site or a bundle of binaries.'
+            + ' check_convertible carries the reasons it gave.',
+    },
+    {
+        marker: 'conversion:unsupported:',
+        phrase: reason => `This origin cannot be converted${aside(reason)}, and no retry changes that.`
+            + ' check_convertible carries the reasons.',
+    },
+    {
+        marker: 'conversion:stage:',
+        phrase: asked => `That decision is not available from where the conversion stands${aside(asked)}.`
+            + ' Call conversion_status for the stage it is on and the decision it takes now.',
+    },
+    {
+        marker: 'conversion:clone-failed:',
+        phrase: () => 'The origin\'s sources could not be fetched. Check the repository still exists and'
+            + ' that the project\'s GitHub connection still reaches it, then'
+            + ' proceed_conversion { "decision": "retry" }.',
+    },
+    {
+        marker: 'conversion:purge-in-place',
+        phrase: () => 'Nothing to purge: the original sources are the project itself (an in-place'
+            + ' repair). It was converted where it stood rather than rebuilt beside a filed-away copy,'
+            + ' so there is no __viable_converted/ to delete and nothing has been removed.',
+    },
+    {
+        marker: 'conversion:publish-origin',
+        phrase: () => 'That would publish onto the repository this project was imported FROM, and its'
+            + ' original sources are still on the volume — the push would write over the user\'s own'
+            + ' code. purge_origin first, or publish to a different repository.',
+    },
+    {
+        marker: 'conversion:relocate-declined',
+        phrase: () => 'The conversion builds the new application around the existing code, which means'
+            + ' moving that code one level down into __viable_converted/; nothing is deleted. The move'
+            + ' was declined, so the conversion stopped here. Start it again and answer yes when it asks.',
+    },
+    // ── A conversion refused by the converter itself, usually reaching a parent on a failed job ──
+    {
+        marker: 'viable-converter:not-convertible:',
+        phrase: reason => `The origin is not an application this platform can convert${aside(reason)}.`,
+    },
+    {
+        marker: 'viable-converter:unsupported-stack:',
+        phrase: stack => `The origin is built on a stack this converter carries no knowledge of${aside(stack)}.`
+            + ' Nothing retries into a stack it cannot read.',
+    },
+    {
+        marker: 'viable-converter:unlinked:',
+        phrase: paths => 'The origin depends on code that is not inside it, so there is no one tree to'
+            + ' convert.' + (paths !== '' ? `\nunlinked: ${paths}` : ''),
+    },
+    {
+        marker: 'viable-converter:stage-order:',
+        phrase: asked => `A conversion stage was asked for out of order${aside(asked)}.`
+            + ' conversion_status says which one comes next.',
+    },
+    {
+        marker: 'viable-converter:capability:',
+        phrase: name => `The conversion needs something this deployment does not provide${aside(name)}.`
+            + ' Nothing the parent agent does changes that; report it.',
+    },
+    {
+        marker: 'viable-converter:too-large:',
+        phrase: bytes => 'The origin is larger than a conversion reads'
+            + (bytes !== '' ? ` (${bytes} bytes)` : '') + '.'
+            + ' Convert a sub-project of it, or bring in a smaller tree.',
+    },
+    {
+        marker: 'viable-converter:taxonomy-missing',
+        phrase: () => 'This step needs what the ANALYSIS stage records, and the volume holds none of'
+            + ' it. Run that stage first — proceed_conversion { "decision": "analyze" }.',
+    },
+    {
+        marker: 'viable-converter:stack-missing',
+        phrase: () => 'This step needs what the INTAKE stage records about the stack, and the volume'
+            + ' holds none of it. The intake is what convert_project runs.',
+    },
+    {
+        marker: 'viable-converter:origin-missing',
+        phrase: () => 'The origin\'s sources are not on the volume: the stage that brings them in has'
+            + ' not run. convert_project starts it.',
+    },
+    {
+        marker: 'viable-converter:origin-purged',
+        phrase: () => 'The original sources were deleted by purge_origin and this needs them. A purge'
+            + ' cannot be undone.',
+    },
+    // ── What the platform refuses to build, whatever asked for it ────────────────────────────────
+    {
+        marker: 'content-refused:',
+        phrase: category => 'The platform will not build this: it describes an application for '
+            + (MODERATION[category] ?? 'something the platform does not host') + '.'
+            + ' The refusal is about the SHAPE of the product, never its sector — say so to the user;'
+            + ' re-sending the same description is refused the same way.',
+    },
+    {
+        marker: 'reserved-name:',
+        phrase: brand => (brand !== ''
+            ? `"${brand}" is another company's name`
+            : 'That name belongs to another company')
+            + ', and a project name becomes part of its public web address. Choose a name of the user\'s'
+            + ' own — the product may still work with that company.',
+    },
+    {
+        marker: 'target-integrity:',
+        phrase: files => 'The files in this project are not a Viable application, so nothing will be'
+            + ' built or started from them.' + (files !== '' ? `\n${files}` : ''),
+    },
+    {
+        marker: 'legacy-target:',
+        phrase: () => 'This project was generated with an earlier application layout the platform no'
+            + ' longer writes into. It keeps running, but no story or change can be applied to it.'
+            + ' reinitialize_project rebuilds it with the current layout and keeps its stories.',
+    },
+    {
+        marker: 'viable-project:missconfigured:',
+        phrase: () => 'This project\'s analysis is missing from its sandbox, so there is nothing to'
+            + ' build a story from. reinitialize_project restores it.',
+    },
+    // ── A balance, rather than a fault ───────────────────────────────────────────────────────────
+    {
+        marker: 'out-of-tokens:conversion-budget',
+        phrase: () => 'The account balance will not cover this conversion stage. conversion_status'
+            + ' carries the estimate; the balance is topped up in the web application.',
+    },
+    {
+        marker: 'out-of-tokens:project-budget',
+        phrase: () => 'The account balance is below the floor a new project needs. It is topped up in'
+            + ' the web application.',
+    },
+    {
+        marker: 'out-of-tokens:story-budget',
+        phrase: () => 'The account balance will not cover developing a story. It is topped up in the'
+            + ' web application.',
+    },
+    // ── The project is busy ──────────────────────────────────────────────────────────────────────
+    {
+        marker: 'viable-project:agent:occupied:',
+        phrase: verb => `The platform is already working on this project${aside(verb)}.`
+            + ' Poll the running job with wait_for and ask again once it settles.',
+    },
+    {
+        // Spelled with its package prefix, unlike every marker above: `locked:` alone is a substring of
+        // ordinary English and of `unlocked:`, and a false match would answer some other refusal with
+        // this sentence.
+        marker: 'viable-agent-common:locked:',
+        phrase: task => `The platform holds this project's lock${aside(task)}.`
+            + ' Poll the running job with wait_for and ask again once it settles.',
+    },
+    {
+        marker: 'git-busy:',
+        phrase: () => 'A git operation is already running on this project. Retry once it settles.',
+    },
+    // ── The connector, from the platform's side of it ────────────────────────────────────────────
+    {
+        marker: 'viable-connect:local-unsupported:',
+        phrase: op => `That addresses infrastructure a local project does not have${aside(op)}:`
+            + ' sandbox lifecycle, production, preview watching and remote git are cloud-target only.',
+    },
+    {
+        marker: 'viable-connect:session-gone:',
+        phrase: () => 'No connector is attached to this project any more, and this needs one. Call the'
+            + ' tool again — a session is opened on demand — then resume_pipeline for the run that'
+            + ' stopped.',
+    },
+    {
+        marker: 'viable-connect:session-not-found:',
+        phrase: () => 'That session has expired or belongs to another profile. Call the tool again; a'
+            + ' session is opened on demand.',
+    },
+    {
+        marker: 'viable-connect:op-timeout:',
+        phrase: () => 'The connector did not answer within the operation\'s own deadline. Retry it.',
+    },
+    {
+        marker: 'viable-connect:op-refused:',
+        phrase: detail => `The connector ran the operation and refused it${aside(detail)}.`,
+    },
+    {
+        marker: 'viable-connect:op-unknown:',
+        phrase: () => 'That operation is unknown, already answered, or belongs to another session.',
+    },
+    // ── The call itself ──────────────────────────────────────────────────────────────────────────
+    {
+        marker: 'viable-api:agent:',
+        phrase: verb => `The platform's agent could not complete this${aside(verb)}.`
+            + ' project_status and conversion_status say where things stand; the call is retryable.',
+    },
+    {
+        marker: 'api:client:auth:',
+        phrase: () => 'The platform refused this access token. It is issued in the web application and'
+            + ' can be revoked there — check VIABLE_API_TOKEN.',
+    },
+    {
+        marker: 'api:client:crashed:',
+        phrase: () => 'The platform errored on this call. Retry it, and read project_status for where'
+            + ' the project actually stands before assuming nothing happened.',
+    },
+    {
+        marker: 'api:client:forbidden',
+        phrase: () => 'This token may not do that: the project belongs to another account, or the'
+            + ' capability is not on this plan.',
+    },
+];
+/** A stack frame, as every runtime prints one. */
+const STACK_FRAME = /^\s+at\s/;
+/** Everything up to the first stack frame — a parent agent can act on none of what follows. */
+const withoutStack = (text) => {
+    const lines = text.split('\n');
+    const frame = lines.findIndex(line => STACK_FRAME.test(line));
+    return (frame < 0 ? lines : lines.slice(0, frame)).join('\n').trim();
+};
+/**
+ * Whether this error is what `ResilientError.ensure` leaves when NOTHING recognised the class.
+ *
+ * Its fall-through converter is `new resilientErrorClass(err.message, err.stack)` against a
+ * constructor whose signature is `(type, message, stack)` — so `type` holds the original MESSAGE
+ * and `message` holds the original STACK, with no marshalling separator anywhere to give the shape
+ * away. Nothing about that path is exotic: `processResponse` in `@owlmeans/api` ensures ANY string
+ * response body, and an edge 502/503 answers in plain text (`upstream connect error …`), so a
+ * gateway failure was handed to the parent agent as a trace of the SDK's own frames.
+ *
+ * It is recognised by the head every runtime prints for a stack — `<Name>: <message>` followed by
+ * the frames — and what survives is the message the runtime put there, which for the plain-text
+ * body IS the refusal. The check is deliberately positional rather than a regex over `<Name>`: the
+ * type can itself be a whole marshalled string carrying newlines, and only the segment BEFORE the
+ * match has to be a single-line error name.
+ */
+const baseConverted = (e) => {
+    if (e.type === '')
+        return false;
+    const at = e.message.indexOf(`: ${e.type}`);
+    if (at < 0)
+        return false;
+    const rest = e.message.slice(at + e.type.length + 2);
+    return !e.message.slice(0, at).includes('\n') && (rest === '' || rest.startsWith('\n'));
+};
+/**
+ * Where the marker actually is, for anything that can carry one.
+ *
+ * `ResilientError.ensure` rebuilds a class this process never registered by putting the whole
+ * marshalled string in `type` and its own local STACK in `message` — and every refusal the
+ * platform raises is such a class, since they are declared in packages the SDK does not depend on.
+ * So the marker can be in either field, and a stored `job.error` carries it as a bare string.
+ *
+ * {@link baseConverted} is asked FIRST, because that rebuild is the one shape where the stack sits
+ * outside the marshalling and the fields are swapped: everything below reads `message` as text and
+ * would hand the trace straight to the reader.
+ */
+const textOf = (e) => {
+    if (typeof e === 'string')
+        return e;
+    if (!(e instanceof Error))
+        return String(e ?? '');
+    if (e instanceof ResilientError && baseConverted(e))
+        return e.type;
+    const type = e instanceof ResilientError ? e.type : '';
+    if (e.message.includes(ResilientError.separator))
+        return e.message;
+    if (type.includes(ResilientError.separator))
+        return type;
+    return e.message !== '' ? e.message : type;
+};
+/**
+ * What a refusal SAYS, with the marshalling and the stack taken off it.
+ *
+ * A marshalled error is `type|||message|||stack`, so the middle segment is the marker and the last
+ * one is a stack trace from a machine the reader has no access to. What is left is the marker
+ * alone — which is the fallback whenever nothing in {@link REFUSALS} recognises it, because a
+ * marker names the refusal even when no sentence has been written for it yet.
+ *
+ * Text that was never marshalled is returned exactly as it is. A stack only ever arrives inside
+ * the marshalling, and the same field carries things that are not refusals at all — a job's
+ * `error` doubles as the build warning a slot recorded, and cutting that at the first line that
+ * looks like a stack frame would throw away the diagnostics somebody asked for.
+ */
+export const refusalMessage = (e) => {
+    const parts = textOf(e).split(ResilientError.separator);
+    return parts.length > 1 ? withoutStack(parts[1] ?? '') : (parts[0] ?? '');
+};
+/** Said where the platform refused and said nothing about why at all. */
+export const UNKNOWN_REFUSAL = 'The platform refused this and said nothing about why. Read'
+    + ' project_status, or conversion_status for a conversion, before retrying.';
+/** Said after a marker no sentence has been written for: the marker names it, this says what next. */
+export const UNPHRASED_REFUSAL = 'That is the marker the platform refused with, and nothing here'
+    + ' has a sentence for it yet. Read conversion_status for a conversion, project_status'
+    + ' otherwise, before deciding whether anything is worth retrying.';
+/**
+ * Wire text a refusal travels as — `package:family:reason`, with any detail after it.
+ *
+ * What separates an unphrased MARKER from the other things this same field carries: a deadline
+ * message, a build warning, a gateway error. Only a marker earns the next-step half, because only
+ * a marker is a refusal the parent can neither read nor act on; a build warning is diagnostics
+ * somebody asked for and is returned exactly as it stands.
+ */
+const MARKER_SHAPE = /^[a-z][\w-]*(?::[\w.-]+)+/;
+/**
+ * The one sentence a parent agent is given for anything that refused it.
+ *
+ * The reader is a language model holding a tool result, and it acts on what it reads: a marshalled
+ * type name followed by a stack trace tells it only that something went wrong somewhere, so it
+ * retries a call that can never succeed, or reports the server as broken. A refusal is an ANSWER —
+ * this origin is the project, that decision is not available here, the balance will not cover it —
+ * and every one of them has something the parent should do next.
+ *
+ * An unknown marker keeps that property rather than dropping it: the marker stays, because it is
+ * the honest answer as the platform grows refusals faster than phrasings, and {@link
+ * UNPHRASED_REFUSAL} names the tool to call — a parent left holding wire text alone has neither.
+ */
+export const refusalPhrase = (e) => {
+    const message = refusalMessage(e);
+    if (message === '')
+        return UNKNOWN_REFUSAL;
+    const known = REFUSALS.find(entry => message.includes(entry.marker));
+    if (known == null) {
+        return MARKER_SHAPE.test(message) ? `${message}\n${UNPHRASED_REFUSAL}` : message;
+    }
+    const detail = message.slice(message.indexOf(known.marker) + known.marker.length)
+        .replace(/^:/, '').trim();
+    return known.phrase(detail);
+};
+//# sourceMappingURL=refusal.js.map

package/build/tools/refusal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"refusal.js","sourceRoot":"","sources":["../../src/tools/refusal.ts"],"names":[],"mappings":"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"}

package/build/tools/types.d.ts

@@ -0,0 +1,83 @@
+import { z } from 'zod';
+import type { ConnectHarness, ConnectLlm, ConnectTarget } from '@owlmeans/viable-common';
+import type { ConnectorApi, LocalExecutor, SessionRuntime } from '../types.js';
+/** Which of the two hosts a tool is being served from. */
+export declare enum ToolHostKind {
+    /** The npx server, on the user's machine, with a local executor. */
+    Stdio = "stdio",
+    /** The platform's own URL-configured endpoint. No machine, no executor. */
+    Http = "http"
+}
+export interface ToolHost {
+    kind: ToolHostKind;
+    target: ConnectTarget;
+    llm: ConnectLlm;
+    harness: ConnectHarness;
+    /** Whether this host can execute anything on a disk. False for the URL-configured one. */
+    hasExecutor: boolean;
+}
+export interface ToolDeps {
+    api: ConnectorApi;
+    host: ToolHost;
+    /** Opened lazily, by the first tool that needs one. */
+    session: () => Promise<SessionRuntime>;
+    /** The current session, if one has been opened. Never opens one. */
+    currentSession: () => SessionRuntime | null;
+    executor?: LocalExecutor;
+    /** The directory a local target lives in. */
+    dir?: string;
+    /** What project the connector is currently working on, and how it is remembered. */
+    attached: () => string | null;
+    attach: (projectId: string) => void;
+    log: (line: string) => void;
+}
+export interface ToolResult {
+    text: string;
+    structured?: object;
+    isError?: boolean;
+}
+export interface ToolDefinition<I extends z.ZodRawShape = z.ZodRawShape> {
+    name: string;
+    title: string;
+    description: string;
+    input: I;
+    /**
+     * Whether this tool is offered at all.
+     *
+     * Hiding rather than failing: a tool a host cannot serve is a tool the parent agent will try
+     * once, be refused, and remember as broken. The catalogue a parent sees is exactly the set of
+     * things that work in its mode.
+     */
+    availability: (host: ToolHost) => boolean;
+    run: (args: Record<string, unknown>, deps: ToolDeps) => Promise<ToolResult>;
+}
+export declare const anyHost: () => boolean;
+export declare const localTarget: (host: ToolHost) => boolean;
+export declare const cloudTarget: (host: ToolHost) => boolean;
+export declare const withExecutor: (host: ToolHost) => boolean;
+export declare const delegatedLlm: (host: ToolHost) => boolean;
+/**
+ * Whether this host can hold a connector SESSION across calls.
+ *
+ * A session is a connector ATTACHED: a process that stays, drains the project's operations and
+ * keeps the model tasks handed to it until the parent agent answers them. The stdio server is
+ * exactly that. The URL-configured host answers one request and forgets — opening a session there
+ * would claim the project's single connector slot, supersede the connector legitimately holding
+ * it, and be abandoned before the first operation was delivered.
+ */
+export declare const sessionCapable: (host: ToolHost) => boolean;
+/**
+ * Whether the platform's own STORY and FREE-FLIGHT calls are this session's to perform.
+ *
+ * That is the delegated mode and nothing else, and it needs two things at once — the account
+ * setting, and a connector able to drain the tasks it produces. A host that cannot hold a session
+ * can never do the draining, whatever the account setting says.
+ *
+ * It decides WORDING, never a tool list. A conversion hands its model calls to the parent by
+ * default on any connector that can hold a session, whatever the account setting says, so
+ * `next_task` / `submit_task_result` are offered on {@link sessionCapable} instead — gated here
+ * they would leave an ordinary session with a conversion blocked on a task it has no tool to
+ * collect.
+ */
+export declare const performsModelTasks: (host: ToolHost) => boolean;
+//# sourceMappingURL=types.d.ts.map

package/build/tools/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/tools/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AACvB,OAAO,KAAK,EAAE,cAAc,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAA;AACxF,OAAO,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AAE9E,0DAA0D;AAC1D,oBAAY,YAAY;IACtB,oEAAoE;IACpE,KAAK,UAAU;IACf,2EAA2E;IAC3E,IAAI,SAAS;CACd;AAED,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,YAAY,CAAA;IAClB,MAAM,EAAE,aAAa,CAAA;IACrB,GAAG,EAAE,UAAU,CAAA;IACf,OAAO,EAAE,cAAc,CAAA;IACvB,0FAA0F;IAC1F,WAAW,EAAE,OAAO,CAAA;CACrB;AAED,MAAM,WAAW,QAAQ;IACvB,GAAG,EAAE,YAAY,CAAA;IACjB,IAAI,EAAE,QAAQ,CAAA;IACd,uDAAuD;IACvD,OAAO,EAAE,MAAM,OAAO,CAAC,cAAc,CAAC,CAAA;IACtC,oEAAoE;IACpE,cAAc,EAAE,MAAM,cAAc,GAAG,IAAI,CAAA;IAC3C,QAAQ,CAAC,EAAE,aAAa,CAAA;IACxB,6CAA6C;IAC7C,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,oFAAoF;IACpF,QAAQ,EAAE,MAAM,MAAM,GAAG,IAAI,CAAA;IAC7B,MAAM,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,IAAI,CAAA;IACnC,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;CAC5B;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAA;IACZ,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,OAAO,CAAC,EAAE,OAAO,CAAA;CAClB;AAED,MAAM,WAAW,cAAc,CAAC,CAAC,SAAS,CAAC,CAAC,WAAW,GAAG,CAAC,CAAC,WAAW;IACrE,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,MAAM,CAAA;IACb,WAAW,EAAE,MAAM,CAAA;IACnB,KAAK,EAAE,CAAC,CAAA;IACR;;;;;;OAMG;IACH,YAAY,EAAE,CAAC,IAAI,EAAE,QAAQ,KAAK,OAAO,CAAA;IACzC,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,IAAI,EAAE,QAAQ,KAAK,OAAO,CAAC,UAAU,CAAC,CAAA;CAC5E;AAED,eAAO,MAAM,OAAO,QAAO,OAAe,CAAA;AAC1C,eAAO,MAAM,WAAW,SAAU,QAAQ,KAAG,OAAkC,CAAA;AAC/E,eAAO,MAAM,WAAW,SAAU,QAAQ,KAAG,OAAkC,CAAA;AAC/E,eAAO,MAAM,YAAY,SAAU,QAAQ,KAAG,OAA2B,CAAA;AACzE,eAAO,MAAM,YAAY,SAAU,QAAQ,KAAG,OAA+B,CAAA;AAE7E;;;;;;;;GAQG;AACH,eAAO,MAAM,cAAc,SAAU,QAAQ,KAAG,OAA2C,CAAA;AAE3F;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,kBAAkB,SAAU,QAAQ,KAAG,OACR,CAAA"}

package/build/tools/types.js

@@ -0,0 +1,38 @@
+/** Which of the two hosts a tool is being served from. */
+export var ToolHostKind;
+(function (ToolHostKind) {
+    /** The npx server, on the user's machine, with a local executor. */
+    ToolHostKind["Stdio"] = "stdio";
+    /** The platform's own URL-configured endpoint. No machine, no executor. */
+    ToolHostKind["Http"] = "http";
+})(ToolHostKind || (ToolHostKind = {}));
+export const anyHost = () => true;
+export const localTarget = (host) => host.target === 'local';
+export const cloudTarget = (host) => host.target === 'cloud';
+export const withExecutor = (host) => host.hasExecutor;
+export const delegatedLlm = (host) => host.llm === 'local';
+/**
+ * Whether this host can hold a connector SESSION across calls.
+ *
+ * A session is a connector ATTACHED: a process that stays, drains the project's operations and
+ * keeps the model tasks handed to it until the parent agent answers them. The stdio server is
+ * exactly that. The URL-configured host answers one request and forgets — opening a session there
+ * would claim the project's single connector slot, supersede the connector legitimately holding
+ * it, and be abandoned before the first operation was delivered.
+ */
+export const sessionCapable = (host) => host.kind === ToolHostKind.Stdio;
+/**
+ * Whether the platform's own STORY and FREE-FLIGHT calls are this session's to perform.
+ *
+ * That is the delegated mode and nothing else, and it needs two things at once — the account
+ * setting, and a connector able to drain the tasks it produces. A host that cannot hold a session
+ * can never do the draining, whatever the account setting says.
+ *
+ * It decides WORDING, never a tool list. A conversion hands its model calls to the parent by
+ * default on any connector that can hold a session, whatever the account setting says, so
+ * `next_task` / `submit_task_result` are offered on {@link sessionCapable} instead — gated here
+ * they would leave an ordinary session with a conversion blocked on a task it has no tool to
+ * collect.
+ */
+export const performsModelTasks = (host) => delegatedLlm(host) && sessionCapable(host);
+//# sourceMappingURL=types.js.map

package/build/tools/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/tools/types.ts"],"names":[],"mappings":"AAIA,0DAA0D;AAC1D,MAAM,CAAN,IAAY,YAKX;AALD,WAAY,YAAY;IACtB,oEAAoE;IACpE,+BAAe,CAAA;IACf,2EAA2E;IAC3E,6BAAa,CAAA;AACf,CAAC,EALW,YAAY,KAAZ,YAAY,QAKvB;AAiDD,MAAM,CAAC,MAAM,OAAO,GAAG,GAAY,EAAE,CAAC,IAAI,CAAA;AAC1C,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,IAAc,EAAW,EAAE,CAAC,IAAI,CAAC,MAAM,KAAK,OAAO,CAAA;AAC/E,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,IAAc,EAAW,EAAE,CAAC,IAAI,CAAC,MAAM,KAAK,OAAO,CAAA;AAC/E,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,IAAc,EAAW,EAAE,CAAC,IAAI,CAAC,WAAW,CAAA;AACzE,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,IAAc,EAAW,EAAE,CAAC,IAAI,CAAC,GAAG,KAAK,OAAO,CAAA;AAE7E;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,IAAc,EAAW,EAAE,CAAC,IAAI,CAAC,IAAI,KAAK,YAAY,CAAC,KAAK,CAAA;AAE3F;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,IAAc,EAAW,EAAE,CAC5D,YAAY,CAAC,IAAI,CAAC,IAAI,cAAc,CAAC,IAAI,CAAC,CAAA"}