@dataverse-kit/agent-kit 0.2.0

package/dist/services.cjs

@@ -0,0 +1,333 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/services/index.ts
+var services_exports = {};
+__export(services_exports, {
+  MockAgentService: () => MockAgentService,
+  NullAgentService: () => NullAgentService,
+  createAgentService: () => createAgentService,
+  decide: () => decide,
+  immediateScheduler: () => immediateScheduler,
+  mockScenarios: () => mockScenarios,
+  realScheduler: () => realScheduler
+});
+module.exports = __toCommonJS(services_exports);
+
+// src/services/scenarios.ts
+var SOURCES = [
+  { id: "src-acct", title: "Contoso Ltd", kind: "dataverse", entityLogicalName: "account", recordId: "11111111-1111-1111-1111-111111111111", snippet: "Annual revenue \xA34.2m, 38 employees." },
+  { id: "src-case", title: "Case 4417 \u2014 invoice mismatch", kind: "dataverse", entityLogicalName: "incident", recordId: "22222222-2222-2222-2222-222222222222", snippet: "Raised 12 Mar, priority High." },
+  { id: "src-kb", title: "KB-208: credit note policy", kind: "knowledge", url: "https://example.invalid/kb/208", snippet: "Credit notes above \xA35,000 require finance approval.", score: 0.82 },
+  { id: "src-doc", title: "Statement-Mar.pdf", kind: "document", snippet: "Page 3 lists the disputed line." },
+  { id: "src-web", title: "Companies House filing", kind: "web", url: "https://example.invalid/ch" }
+];
+var mockScenarios = {
+  happy: {
+    text: "Contoso has three open cases. The oldest, case 4417, has been waiting eleven days for a credit note.",
+    status: "succeeded",
+    suggestions: ["Draft a credit note", "Show all three cases", "Who owns case 4417?"]
+  },
+  // ★ FIVE sources, but the text cites only [3] and [1] — and out of order. The panel must
+  //   show TWO, renumbered 1 and 2 in first-appearance order. A fixture where every source
+  //   is cited cannot tell a correct implementation from one that lists everything it was given.
+  grounded: {
+    text: "Credit notes over \xA35,000 need finance approval [3], and case 4417 is for \xA36,200 [1]. So this one needs sign-off.",
+    status: "succeeded",
+    sources: SOURCES
+  },
+  toolApproval: {
+    text: "I can raise the credit note for you \u2014 approve the details below and I will submit it.",
+    status: "succeeded",
+    toolCall: {
+      id: "call-1",
+      name: "create_credit_note",
+      argumentsJson: '{"accountId":"11111111-1111-1111-1111-111111111111","amount":6200,"currency":"GBP","reason":"Invoice mismatch, case 4417"}',
+      status: "proposed",
+      requiresApproval: true
+    }
+  },
+  toolAuto: {
+    text: "I checked the balance for you.",
+    status: "succeeded",
+    toolCall: { id: "call-2", name: "get_account_balance", argumentsJson: '{"accountId":"1111"}', status: "running" },
+    autoToolResult: '{"balance":6200,"currency":"GBP"}'
+  },
+  // ★ blocked and refused MUST look different on screen: a content filter fired, versus the
+  //   model declining. They need different fixes, so they are different states.
+  blocked: {
+    text: "I can\u2019t help with that request.",
+    status: "blocked",
+    guarded: true,
+    failureMessage: "The response was withheld by the content filter.",
+    failureCode: "content_filter",
+    recoverable: false
+  },
+  refused: {
+    text: "I don\u2019t have enough information to answer that safely. Could you say which account you mean?",
+    status: "refused",
+    failureMessage: "The agent declined to answer.",
+    recoverable: true
+  },
+  error: {
+    text: "",
+    status: "error",
+    failureMessage: "The agent is rate limited. Try again shortly.",
+    failureCode: "rate_limited",
+    recoverable: true,
+    retryAfterMs: 4e3
+  },
+  notProvisioned: {
+    text: "",
+    status: "notProvisioned",
+    failureMessage: "No Foundry project is configured for this environment.",
+    failureCode: "not_provisioned",
+    recoverable: false,
+    unavailable: true
+  },
+  cancelled: {
+    text: "Let me pull the last six months of activity for Contoso and work through it case by case, starting with the oldest\u2026",
+    status: "cancelled",
+    failureMessage: "Stopped."
+  },
+  // The fixture the autoscroll and live-region gates run against: enough deltas that
+  // "once, not per token" is a meaningful distinction.
+  longAnswer: {
+    text: Array.from({ length: 200 }, (_, i) => `word${i + 1}`).join(" "),
+    status: "succeeded"
+  },
+  throws: {
+    text: "partial\u2026",
+    status: "error",
+    throwsMidStream: true,
+    failureMessage: "never reached \u2014 the iterator throws instead"
+  }
+};
+
+// src/services/MockAgentService.ts
+var realScheduler = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+var immediateScheduler = () => Promise.resolve();
+function mulberry32(seed) {
+  let a = seed >>> 0;
+  return () => {
+    a = a + 1831565813 >>> 0;
+    let t = Math.imul(a ^ a >>> 15, 1 | a);
+    t = t + Math.imul(t ^ t >>> 7, 61 | t) ^ t;
+    return ((t ^ t >>> 14) >>> 0) / 4294967296;
+  };
+}
+var MockAgentService = class {
+  constructor(options = {}) {
+    this.name = "mock";
+    this.scenarioName = options.scenario ?? "happy";
+    this.scenario = mockScenarios[this.scenarioName];
+    this.scheduler = options.scheduler ?? realScheduler;
+    this.firstTokenMs = options.firstTokenMs ?? 400;
+    this.chunkMs = options.chunkMs ?? 28;
+    this.rand = mulberry32(options.seed ?? 1);
+    this.availabilityOverride = options.availability;
+  }
+  async isAvailable() {
+    if (this.availabilityOverride) return this.availabilityOverride;
+    if (this.scenario.unavailable) {
+      return {
+        available: false,
+        status: "notProvisioned",
+        reason: this.scenario.failureMessage ?? "Not provisioned."
+      };
+    }
+    return {
+      available: true,
+      capabilities: { streaming: true, tools: true, citations: true, attachments: true, cancel: true }
+    };
+  }
+  /**
+   * A prompt can select a scenario (`/blocked`, `/tool`, `/error`), so one story can walk
+   * every state without remounting.
+   */
+  resolveScenario(promptText) {
+    const slash = promptText.trim().match(/^\/(\w+)/)?.[1];
+    if (slash && slash in mockScenarios) {
+      return { name: slash, scenario: mockScenarios[slash] };
+    }
+    return { name: this.scenarioName, scenario: this.scenario };
+  }
+  async *send(turn) {
+    const { scenario } = this.resolveScenario(turn.text);
+    const messageId = `mock-${Math.floor(this.rand() * 1e9).toString(36)}`;
+    const turnId = `turn-${messageId}`;
+    const provider = this.name;
+    const finish = (result) => ({
+      type: "turn_end",
+      turnId,
+      messageId,
+      result: { ...result, provider }
+    });
+    yield { type: "turn_start", turnId, messageId, provider, model: "mock-1" };
+    if (turn.cancelSignal?.aborted) {
+      yield finish({ status: "cancelled", text: "", failure: { status: "cancelled", message: "Stopped." } });
+      return;
+    }
+    if (scenario.status === "notProvisioned" || scenario.status === "error" && !scenario.text) {
+      await this.scheduler(this.firstTokenMs);
+      yield finish({
+        status: scenario.status,
+        text: "",
+        failure: {
+          status: scenario.status,
+          message: scenario.failureMessage ?? "Failed.",
+          code: scenario.failureCode,
+          recoverable: scenario.recoverable,
+          retryAfterMs: scenario.retryAfterMs
+        }
+      });
+      return;
+    }
+    if (scenario.sources) {
+      yield { type: "status", messageId, label: "Searching Dataverse\u2026" };
+      await this.scheduler(this.firstTokenMs);
+      yield { type: "sources", messageId, sources: scenario.sources };
+    }
+    if (scenario.thinking) {
+      yield { type: "thinking_delta", messageId, text: scenario.thinking };
+    }
+    if (scenario.toolCall) {
+      yield { type: "tool_call", messageId, call: scenario.toolCall };
+      if (scenario.autoToolResult !== void 0) {
+        await this.scheduler(this.chunkMs);
+        yield {
+          type: "tool_result",
+          messageId,
+          callId: scenario.toolCall.id,
+          status: "succeeded",
+          resultText: scenario.autoToolResult
+        };
+      }
+    }
+    const chunks = scenario.chunks ?? scenario.text.split(/(?<=\s)/);
+    await this.scheduler(this.firstTokenMs);
+    let emitted = "";
+    for (const [i, chunk] of chunks.entries()) {
+      if (turn.cancelSignal?.aborted) {
+        yield finish({
+          status: "cancelled",
+          text: emitted,
+          failure: { status: "cancelled", message: "Stopped." }
+        });
+        return;
+      }
+      if (scenario.throwsMidStream && i === Math.floor(chunks.length / 2)) {
+        throw new Error("mock transport exploded mid-stream");
+      }
+      emitted += chunk;
+      yield { type: "text_delta", messageId, text: chunk };
+      await this.scheduler(this.chunkMs);
+    }
+    if (scenario.suggestions) {
+      yield { type: "suggestions", messageId, prompts: scenario.suggestions };
+    }
+    const failed = scenario.status !== "succeeded";
+    yield finish({
+      status: scenario.status,
+      text: emitted,
+      guarded: scenario.guarded,
+      usage: {
+        inputTokens: 128,
+        outputTokens: chunks.length,
+        costUsd: Number((chunks.length * 2e-6).toFixed(6)),
+        durationMs: this.firstTokenMs + chunks.length * this.chunkMs,
+        model: "mock-1"
+      },
+      failure: failed ? {
+        status: scenario.status,
+        message: scenario.failureMessage ?? "Failed.",
+        code: scenario.failureCode,
+        recoverable: scenario.recoverable,
+        retryAfterMs: scenario.retryAfterMs
+      } : void 0
+    });
+  }
+};
+
+// src/services/NullAgentService.ts
+var NullAgentService = class {
+  constructor() {
+    this.name = "none";
+  }
+  async isAvailable() {
+    return {
+      available: false,
+      status: "notProvisioned",
+      reason: "No agent provider is configured for this host."
+    };
+  }
+  async *send(turn) {
+    const messageId = `null-${Date.now()}`;
+    const turnId = `turn-${messageId}`;
+    void turn;
+    yield { type: "turn_start", turnId, messageId, provider: this.name };
+    yield {
+      type: "turn_end",
+      turnId,
+      messageId,
+      result: {
+        status: "notProvisioned",
+        text: "",
+        provider: this.name,
+        failure: {
+          status: "notProvisioned",
+          message: "No agent provider is configured for this host.",
+          code: "not_provisioned",
+          recoverable: false
+        }
+      }
+    };
+  }
+};
+
+// src/services/createAgentService.ts
+function decide(config) {
+  switch (config.provider) {
+    case "custom":
+      return config.factory ? { provider: config.factory(), reason: "explicit factory (provider: custom)" } : { provider: new NullAgentService(), reason: "provider: custom but no factory supplied" };
+    case "mock":
+      return { provider: new MockAgentService(), reason: "provider: mock" };
+    case "none":
+      return { provider: new NullAgentService(), reason: "provider: none (the default)" };
+    default:
+      return {
+        provider: new NullAgentService(),
+        reason: `unrecognised provider ${String(config.provider)} \u2014 falling back to none`
+      };
+  }
+}
+function createAgentService(config = { provider: "none" }) {
+  return decide(config).provider;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  MockAgentService,
+  NullAgentService,
+  createAgentService,
+  decide,
+  immediateScheduler,
+  mockScenarios,
+  realScheduler
+});
+//# sourceMappingURL=services.cjs.map

package/dist/services.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/services/index.ts","../src/services/scenarios.ts","../src/services/MockAgentService.ts","../src/services/NullAgentService.ts","../src/services/createAgentService.ts"],"sourcesContent":["// @dataverse-kit/agent-kit/services — the seam and the fake.\n//\n// Framework-agnostic (no react, no @fluentui), so a transport adapter can implement\n// IAgentService in a Node broker or an Azure Function and share these types with the browser.\n//\n// ★ The kit ships NO real transport. Foundry, Copilot Studio / Direct Line and broker\n//   adapters belong in the consuming app, because they are where credentials live and the\n//   kit must never hold one.\nexport type {\n  AgentAttachment,\n  AgentAvailability,\n  AgentCapabilities,\n  AgentCitation,\n  AgentEvent,\n  AgentFailure,\n  AgentMessage,\n  AgentParticipant,\n  AgentProviderName,\n  AgentRole,\n  AgentRunStatus,\n  AgentServiceConfig,\n  AgentSource,\n  AgentToolCall,\n  AgentTurn,\n  AgentTurnResult,\n  AgentUsage,\n  IAgentService,\n  ToolCallStatus,\n} from '../core/protocol';\n\nexport { MockAgentService, realScheduler, immediateScheduler } from './MockAgentService';\nexport type { MockAgentServiceOptions, Scheduler } from './MockAgentService';\nexport { NullAgentService } from './NullAgentService';\nexport { createAgentService, decide } from './createAgentService';\nexport { mockScenarios } from './scenarios';\nexport type { MockScenario, MockScenarioName } from './scenarios';\n","import type { AgentRunStatus, AgentSource, AgentToolCall } from '../core/protocol';\n\n/**\n * What the mock can be driven to do. There is one scenario per terminal state plus the\n * interesting mid-stream shapes, because a Storybook that cannot SHOW a state is a Storybook\n * in which that state is never reviewed — and a test suite that cannot REACH one is a suite\n * in which it is never asserted.\n */\nexport type MockScenarioName =\n  | 'happy'\n  | 'grounded'\n  | 'toolApproval'\n  | 'toolAuto'\n  | 'blocked'\n  | 'refused'\n  | 'error'\n  | 'notProvisioned'\n  | 'cancelled'\n  | 'longAnswer'\n  | 'throws';\n\nexport interface MockScenario {\n  /** The answer, streamed word by word unless `chunks` overrides it. */\n  text: string;\n  chunks?: string[];\n  status: AgentRunStatus;\n  guarded?: boolean;\n  failureMessage?: string;\n  failureCode?: string;\n  recoverable?: boolean;\n  retryAfterMs?: number;\n  sources?: AgentSource[];\n  /** Emitted mid-stream, before the terminal event. */\n  toolCall?: AgentToolCall;\n  /** When set, the tool resolves itself rather than waiting for host approval. */\n  autoToolResult?: string;\n  suggestions?: string[];\n  thinking?: string;\n  /** Throw from inside the iterator — the failure channel a Promise-shaped seam does not have. */\n  throwsMidStream?: boolean;\n  /** Never becomes available; `send()` still yields a well-formed turn. */\n  unavailable?: boolean;\n}\n\nconst SOURCES: AgentSource[] = [\n  { id: 'src-acct', title: 'Contoso Ltd', kind: 'dataverse', entityLogicalName: 'account', recordId: '11111111-1111-1111-1111-111111111111', snippet: 'Annual revenue £4.2m, 38 employees.' },\n  { id: 'src-case', title: 'Case 4417 — invoice mismatch', kind: 'dataverse', entityLogicalName: 'incident', recordId: '22222222-2222-2222-2222-222222222222', snippet: 'Raised 12 Mar, priority High.' },\n  { id: 'src-kb', title: 'KB-208: credit note policy', kind: 'knowledge', url: 'https://example.invalid/kb/208', snippet: 'Credit notes above £5,000 require finance approval.', score: 0.82 },\n  { id: 'src-doc', title: 'Statement-Mar.pdf', kind: 'document', snippet: 'Page 3 lists the disputed line.' },\n  { id: 'src-web', title: 'Companies House filing', kind: 'web', url: 'https://example.invalid/ch' },\n];\n\nexport const mockScenarios: Record<MockScenarioName, MockScenario> = {\n  happy: {\n    text: 'Contoso has three open cases. The oldest, case 4417, has been waiting eleven days for a credit note.',\n    status: 'succeeded',\n    suggestions: ['Draft a credit note', 'Show all three cases', 'Who owns case 4417?'],\n  },\n\n  // ★ FIVE sources, but the text cites only [3] and [1] — and out of order. The panel must\n  //   show TWO, renumbered 1 and 2 in first-appearance order. A fixture where every source\n  //   is cited cannot tell a correct implementation from one that lists everything it was given.\n  grounded: {\n    text: 'Credit notes over £5,000 need finance approval [3], and case 4417 is for £6,200 [1]. So this one needs sign-off.',\n    status: 'succeeded',\n    sources: SOURCES,\n  },\n\n  toolApproval: {\n    text: 'I can raise the credit note for you — approve the details below and I will submit it.',\n    status: 'succeeded',\n    toolCall: {\n      id: 'call-1',\n      name: 'create_credit_note',\n      argumentsJson: '{\"accountId\":\"11111111-1111-1111-1111-111111111111\",\"amount\":6200,\"currency\":\"GBP\",\"reason\":\"Invoice mismatch, case 4417\"}',\n      status: 'proposed',\n      requiresApproval: true,\n    },\n  },\n\n  toolAuto: {\n    text: 'I checked the balance for you.',\n    status: 'succeeded',\n    toolCall: { id: 'call-2', name: 'get_account_balance', argumentsJson: '{\"accountId\":\"1111\"}', status: 'running' },\n    autoToolResult: '{\"balance\":6200,\"currency\":\"GBP\"}',\n  },\n\n  // ★ blocked and refused MUST look different on screen: a content filter fired, versus the\n  //   model declining. They need different fixes, so they are different states.\n  blocked: {\n    text: 'I can’t help with that request.',\n    status: 'blocked',\n    guarded: true,\n    failureMessage: 'The response was withheld by the content filter.',\n    failureCode: 'content_filter',\n    recoverable: false,\n  },\n\n  refused: {\n    text: 'I don’t have enough information to answer that safely. Could you say which account you mean?',\n    status: 'refused',\n    failureMessage: 'The agent declined to answer.',\n    recoverable: true,\n  },\n\n  error: {\n    text: '',\n    status: 'error',\n    failureMessage: 'The agent is rate limited. Try again shortly.',\n    failureCode: 'rate_limited',\n    recoverable: true,\n    retryAfterMs: 4000,\n  },\n\n  notProvisioned: {\n    text: '',\n    status: 'notProvisioned',\n    failureMessage: 'No Foundry project is configured for this environment.',\n    failureCode: 'not_provisioned',\n    recoverable: false,\n    unavailable: true,\n  },\n\n  cancelled: {\n    text: 'Let me pull the last six months of activity for Contoso and work through it case by case, starting with the oldest…',\n    status: 'cancelled',\n    failureMessage: 'Stopped.',\n  },\n\n  // The fixture the autoscroll and live-region gates run against: enough deltas that\n  // \"once, not per token\" is a meaningful distinction.\n  longAnswer: {\n    text: Array.from({ length: 200 }, (_, i) => `word${i + 1}`).join(' '),\n    status: 'succeeded',\n  },\n\n  throws: {\n    text: 'partial…',\n    status: 'error',\n    throwsMidStream: true,\n    failureMessage: 'never reached — the iterator throws instead',\n  },\n};\n","import type {\n  AgentAvailability,\n  AgentEvent,\n  AgentTurn,\n  AgentTurnResult,\n  IAgentService,\n} from '../core/protocol';\nimport { mockScenarios, type MockScenario, type MockScenarioName } from './scenarios';\n\n/** Injectable so tests run at zero delay and Storybook runs at human speed. */\nexport type Scheduler = (ms: number) => Promise<void>;\n\nexport const realScheduler: Scheduler = (ms) =>\n  new Promise((resolve) => setTimeout(resolve, ms));\nexport const immediateScheduler: Scheduler = () => Promise.resolve();\n\nexport interface MockAgentServiceOptions {\n  scenario?: MockScenarioName;\n  scheduler?: Scheduler;\n  /** Delay before the first token, so the typing indicator is visible and screenshottable. */\n  firstTokenMs?: number;\n  chunkMs?: number;\n  /**\n   * ★ A CONSTRUCTOR ARGUMENT, never module state.\n   *\n   * tsup runs with `splitting: false`, so every entry gets a self-contained bundle and any\n   * module-level `let` is physically duplicated per entry — a story importing from `.` and a\n   * test importing from `./services` would get two independent counters. Measured on\n   * surface-kit: three copies of the same function body across its entries.\n   */\n  seed?: number;\n  /** Override availability; otherwise derived from the scenario. */\n  availability?: AgentAvailability;\n}\n\n/** A tiny deterministic PRNG so Chromatic snapshots do not drift. */\nfunction mulberry32(seed: number): () => number {\n  let a = seed >>> 0;\n  return () => {\n    a = (a + 0x6d2b79f5) >>> 0;\n    let t = Math.imul(a ^ (a >>> 15), 1 | a);\n    t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;\n    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;\n  };\n}\n\n/**\n * The in-package fake. It is the only \"provider\" agent-kit ships: real transports (Foundry,\n * Copilot Studio, a broker) live in the consuming app, so the kit never holds a credential.\n *\n * ★ It can reach EVERY `AgentRunStatus`. A test asserts that, because a mock that cannot\n *   produce a state is a state nothing downstream is ever tested against.\n */\nexport class MockAgentService implements IAgentService {\n  readonly name = 'mock';\n\n  private readonly scenario: MockScenario;\n  private readonly scenarioName: MockScenarioName;\n  private readonly scheduler: Scheduler;\n  private readonly firstTokenMs: number;\n  private readonly chunkMs: number;\n  private readonly rand: () => number;\n  private readonly availabilityOverride?: AgentAvailability;\n\n  constructor(options: MockAgentServiceOptions = {}) {\n    this.scenarioName = options.scenario ?? 'happy';\n    this.scenario = mockScenarios[this.scenarioName];\n    this.scheduler = options.scheduler ?? realScheduler;\n    this.firstTokenMs = options.firstTokenMs ?? 400;\n    this.chunkMs = options.chunkMs ?? 28;\n    this.rand = mulberry32(options.seed ?? 1);\n    this.availabilityOverride = options.availability;\n  }\n\n  async isAvailable(): Promise<AgentAvailability> {\n    if (this.availabilityOverride) return this.availabilityOverride;\n    if (this.scenario.unavailable) {\n      return {\n        available: false,\n        status: 'notProvisioned',\n        reason: this.scenario.failureMessage ?? 'Not provisioned.',\n      };\n    }\n    return {\n      available: true,\n      capabilities: { streaming: true, tools: true, citations: true, attachments: true, cancel: true },\n    };\n  }\n\n  /**\n   * A prompt can select a scenario (`/blocked`, `/tool`, `/error`), so one story can walk\n   * every state without remounting.\n   */\n  private resolveScenario(promptText: string): { name: MockScenarioName; scenario: MockScenario } {\n    const slash = promptText.trim().match(/^\\/(\\w+)/)?.[1] as MockScenarioName | undefined;\n    if (slash && slash in mockScenarios) {\n      return { name: slash, scenario: mockScenarios[slash] };\n    }\n    return { name: this.scenarioName, scenario: this.scenario };\n  }\n\n  async *send(turn: AgentTurn): AsyncIterable<AgentEvent> {\n    const { scenario } = this.resolveScenario(turn.text);\n    const messageId = `mock-${Math.floor(this.rand() * 1e9).toString(36)}`;\n    const turnId = `turn-${messageId}`;\n    const provider = this.name;\n\n    const finish = (result: Omit<AgentTurnResult, 'provider'>): AgentEvent => ({\n      type: 'turn_end',\n      turnId,\n      messageId,\n      result: { ...result, provider },\n    });\n\n    yield { type: 'turn_start', turnId, messageId, provider, model: 'mock-1' };\n\n    if (turn.cancelSignal?.aborted) {\n      yield finish({ status: 'cancelled', text: '', failure: { status: 'cancelled', message: 'Stopped.' } });\n      return;\n    }\n\n    // Terminal-before-any-text scenarios still emit a well-formed turn.\n    if (scenario.status === 'notProvisioned' || (scenario.status === 'error' && !scenario.text)) {\n      await this.scheduler(this.firstTokenMs);\n      yield finish({\n        status: scenario.status,\n        text: '',\n        failure: {\n          status: scenario.status,\n          message: scenario.failureMessage ?? 'Failed.',\n          code: scenario.failureCode,\n          recoverable: scenario.recoverable,\n          retryAfterMs: scenario.retryAfterMs,\n        },\n      });\n      return;\n    }\n\n    if (scenario.sources) {\n      yield { type: 'status', messageId, label: 'Searching Dataverse…' };\n      await this.scheduler(this.firstTokenMs);\n      yield { type: 'sources', messageId, sources: scenario.sources };\n    }\n\n    if (scenario.thinking) {\n      yield { type: 'thinking_delta', messageId, text: scenario.thinking };\n    }\n\n    if (scenario.toolCall) {\n      yield { type: 'tool_call', messageId, call: scenario.toolCall };\n      if (scenario.autoToolResult !== undefined) {\n        await this.scheduler(this.chunkMs);\n        yield {\n          type: 'tool_result',\n          messageId,\n          callId: scenario.toolCall.id,\n          status: 'succeeded',\n          resultText: scenario.autoToolResult,\n        };\n      }\n    }\n\n    const chunks = scenario.chunks ?? scenario.text.split(/(?<=\\s)/);\n    await this.scheduler(this.firstTokenMs);\n\n    let emitted = '';\n    for (const [i, chunk] of chunks.entries()) {\n      if (turn.cancelSignal?.aborted) {\n        yield finish({\n          status: 'cancelled',\n          text: emitted,\n          failure: { status: 'cancelled', message: 'Stopped.' },\n        });\n        return;\n      }\n      if (scenario.throwsMidStream && i === Math.floor(chunks.length / 2)) {\n        // The failure channel an AsyncIterable has and a Promise does not. A consumer must\n        // surface this as a notice, not by unmounting the tree.\n        throw new Error('mock transport exploded mid-stream');\n      }\n      emitted += chunk;\n      yield { type: 'text_delta', messageId, text: chunk };\n      await this.scheduler(this.chunkMs);\n    }\n\n    if (scenario.suggestions) {\n      yield { type: 'suggestions', messageId, prompts: scenario.suggestions };\n    }\n\n    const failed = scenario.status !== 'succeeded';\n    yield finish({\n      status: scenario.status,\n      text: emitted,\n      guarded: scenario.guarded,\n      usage: {\n        inputTokens: 128,\n        outputTokens: chunks.length,\n        costUsd: Number((chunks.length * 0.000002).toFixed(6)),\n        durationMs: this.firstTokenMs + chunks.length * this.chunkMs,\n        model: 'mock-1',\n      },\n      failure: failed\n        ? {\n            status: scenario.status as Exclude<typeof scenario.status, 'succeeded'>,\n            message: scenario.failureMessage ?? 'Failed.',\n            code: scenario.failureCode,\n            recoverable: scenario.recoverable,\n            retryAfterMs: scenario.retryAfterMs,\n          }\n        : undefined,\n    });\n  }\n}\n","import type { AgentAvailability, AgentEvent, AgentTurn, IAgentService } from '../core/protocol';\n\n/**\n * The default provider: answers nothing, politely.\n *\n * ★ `none` is the DEFAULT and must stay so. A kit dropped into a host nobody has wired must\n *   not silently start talking to a service because someone shipped a new build. Carried\n *   from `ILlmService`, where the same rule is load-bearing in a regulated process.\n *\n * ★ It still yields a well-formed turn — `turn_start` then one `turn_end` — rather than\n *   throwing or yielding nothing. An unconfigured kit should render \"not configured\", not\n *   a spinner that never resolves.\n */\nexport class NullAgentService implements IAgentService {\n  readonly name = 'none';\n\n  async isAvailable(): Promise<AgentAvailability> {\n    return {\n      available: false,\n      status: 'notProvisioned',\n      reason: 'No agent provider is configured for this host.',\n    };\n  }\n\n  async *send(turn: AgentTurn): AsyncIterable<AgentEvent> {\n    const messageId = `null-${Date.now()}`;\n    const turnId = `turn-${messageId}`;\n    void turn;\n    yield { type: 'turn_start', turnId, messageId, provider: this.name };\n    yield {\n      type: 'turn_end',\n      turnId,\n      messageId,\n      result: {\n        status: 'notProvisioned',\n        text: '',\n        provider: this.name,\n        failure: {\n          status: 'notProvisioned',\n          message: 'No agent provider is configured for this host.',\n          code: 'not_provisioned',\n          recoverable: false,\n        },\n      },\n    };\n  }\n}\n","import type { AgentServiceConfig, IAgentService } from '../core/protocol';\nimport { MockAgentService } from './MockAgentService';\nimport { NullAgentService } from './NullAgentService';\n\nexport interface ServiceDecision {\n  provider: IAgentService;\n  /** Why this one was chosen — surfaced in diagnostics so a misconfiguration is legible. */\n  reason: string;\n}\n\n/**\n * Provider selection, as ONE ladder.\n *\n * ★ `decide()` is exported alongside `createAgentService()` and they share a return type, so\n *   the factory and any diagnostics view cannot drift — the shape `ServiceFactory.decide()`\n *   uses in `@dataverse-kit/api-service` for exactly the same reason.\n *\n * ★ An UNRECOGNISED provider name falls back to `none`, never to a working provider. Carried\n *   from `createLlmService`: a typo must produce silence, not an unintended call to a model.\n */\nexport function decide(config: AgentServiceConfig): ServiceDecision {\n  switch (config.provider) {\n    case 'custom':\n      return config.factory\n        ? { provider: config.factory(), reason: 'explicit factory (provider: custom)' }\n        : { provider: new NullAgentService(), reason: 'provider: custom but no factory supplied' };\n    case 'mock':\n      return { provider: new MockAgentService(), reason: 'provider: mock' };\n    case 'none':\n      return { provider: new NullAgentService(), reason: 'provider: none (the default)' };\n    default:\n      return {\n        provider: new NullAgentService(),\n        reason: `unrecognised provider ${String(config.provider)} — falling back to none`,\n      };\n  }\n}\n\nexport function createAgentService(\n  config: AgentServiceConfig = { provider: 'none' },\n): IAgentService {\n  return decide(config).provider;\n}\n"],"mappings":"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","names":[]}

package/dist/services.d.cts

@@ -0,0 +1,118 @@
+import { c as AgentRunStatus, f as AgentSource, h as AgentToolCall, I as IAgentService, d as AgentAvailability, o as AgentTurn, k as AgentEvent, n as AgentServiceConfig } from './protocol-CZJ1v9Hq.cjs';
+export { i as AgentAttachment, j as AgentCapabilities, g as AgentCitation, b as AgentFailure, A as AgentMessage, a as AgentParticipant, l as AgentProviderName, m as AgentRole, p as AgentTurnResult, e as AgentUsage, T as ToolCallStatus } from './protocol-CZJ1v9Hq.cjs';
+
+/**
+ * What the mock can be driven to do. There is one scenario per terminal state plus the
+ * interesting mid-stream shapes, because a Storybook that cannot SHOW a state is a Storybook
+ * in which that state is never reviewed — and a test suite that cannot REACH one is a suite
+ * in which it is never asserted.
+ */
+type MockScenarioName = 'happy' | 'grounded' | 'toolApproval' | 'toolAuto' | 'blocked' | 'refused' | 'error' | 'notProvisioned' | 'cancelled' | 'longAnswer' | 'throws';
+interface MockScenario {
+    /** The answer, streamed word by word unless `chunks` overrides it. */
+    text: string;
+    chunks?: string[];
+    status: AgentRunStatus;
+    guarded?: boolean;
+    failureMessage?: string;
+    failureCode?: string;
+    recoverable?: boolean;
+    retryAfterMs?: number;
+    sources?: AgentSource[];
+    /** Emitted mid-stream, before the terminal event. */
+    toolCall?: AgentToolCall;
+    /** When set, the tool resolves itself rather than waiting for host approval. */
+    autoToolResult?: string;
+    suggestions?: string[];
+    thinking?: string;
+    /** Throw from inside the iterator — the failure channel a Promise-shaped seam does not have. */
+    throwsMidStream?: boolean;
+    /** Never becomes available; `send()` still yields a well-formed turn. */
+    unavailable?: boolean;
+}
+declare const mockScenarios: Record<MockScenarioName, MockScenario>;
+
+/** Injectable so tests run at zero delay and Storybook runs at human speed. */
+type Scheduler = (ms: number) => Promise<void>;
+declare const realScheduler: Scheduler;
+declare const immediateScheduler: Scheduler;
+interface MockAgentServiceOptions {
+    scenario?: MockScenarioName;
+    scheduler?: Scheduler;
+    /** Delay before the first token, so the typing indicator is visible and screenshottable. */
+    firstTokenMs?: number;
+    chunkMs?: number;
+    /**
+     * ★ A CONSTRUCTOR ARGUMENT, never module state.
+     *
+     * tsup runs with `splitting: false`, so every entry gets a self-contained bundle and any
+     * module-level `let` is physically duplicated per entry — a story importing from `.` and a
+     * test importing from `./services` would get two independent counters. Measured on
+     * surface-kit: three copies of the same function body across its entries.
+     */
+    seed?: number;
+    /** Override availability; otherwise derived from the scenario. */
+    availability?: AgentAvailability;
+}
+/**
+ * The in-package fake. It is the only "provider" agent-kit ships: real transports (Foundry,
+ * Copilot Studio, a broker) live in the consuming app, so the kit never holds a credential.
+ *
+ * ★ It can reach EVERY `AgentRunStatus`. A test asserts that, because a mock that cannot
+ *   produce a state is a state nothing downstream is ever tested against.
+ */
+declare class MockAgentService implements IAgentService {
+    readonly name = "mock";
+    private readonly scenario;
+    private readonly scenarioName;
+    private readonly scheduler;
+    private readonly firstTokenMs;
+    private readonly chunkMs;
+    private readonly rand;
+    private readonly availabilityOverride?;
+    constructor(options?: MockAgentServiceOptions);
+    isAvailable(): Promise<AgentAvailability>;
+    /**
+     * A prompt can select a scenario (`/blocked`, `/tool`, `/error`), so one story can walk
+     * every state without remounting.
+     */
+    private resolveScenario;
+    send(turn: AgentTurn): AsyncIterable<AgentEvent>;
+}
+
+/**
+ * The default provider: answers nothing, politely.
+ *
+ * ★ `none` is the DEFAULT and must stay so. A kit dropped into a host nobody has wired must
+ *   not silently start talking to a service because someone shipped a new build. Carried
+ *   from `ILlmService`, where the same rule is load-bearing in a regulated process.
+ *
+ * ★ It still yields a well-formed turn — `turn_start` then one `turn_end` — rather than
+ *   throwing or yielding nothing. An unconfigured kit should render "not configured", not
+ *   a spinner that never resolves.
+ */
+declare class NullAgentService implements IAgentService {
+    readonly name = "none";
+    isAvailable(): Promise<AgentAvailability>;
+    send(turn: AgentTurn): AsyncIterable<AgentEvent>;
+}
+
+interface ServiceDecision {
+    provider: IAgentService;
+    /** Why this one was chosen — surfaced in diagnostics so a misconfiguration is legible. */
+    reason: string;
+}
+/**
+ * Provider selection, as ONE ladder.
+ *
+ * ★ `decide()` is exported alongside `createAgentService()` and they share a return type, so
+ *   the factory and any diagnostics view cannot drift — the shape `ServiceFactory.decide()`
+ *   uses in `@dataverse-kit/api-service` for exactly the same reason.
+ *
+ * ★ An UNRECOGNISED provider name falls back to `none`, never to a working provider. Carried
+ *   from `createLlmService`: a typo must produce silence, not an unintended call to a model.
+ */
+declare function decide(config: AgentServiceConfig): ServiceDecision;
+declare function createAgentService(config?: AgentServiceConfig): IAgentService;
+
+export { AgentAvailability, AgentEvent, AgentRunStatus, AgentServiceConfig, AgentSource, AgentToolCall, AgentTurn, IAgentService, MockAgentService, type MockAgentServiceOptions, type MockScenario, type MockScenarioName, NullAgentService, type Scheduler, createAgentService, decide, immediateScheduler, mockScenarios, realScheduler };

package/dist/services.d.ts

@@ -0,0 +1,118 @@
+import { c as AgentRunStatus, f as AgentSource, h as AgentToolCall, I as IAgentService, d as AgentAvailability, o as AgentTurn, k as AgentEvent, n as AgentServiceConfig } from './protocol-CZJ1v9Hq.js';
+export { i as AgentAttachment, j as AgentCapabilities, g as AgentCitation, b as AgentFailure, A as AgentMessage, a as AgentParticipant, l as AgentProviderName, m as AgentRole, p as AgentTurnResult, e as AgentUsage, T as ToolCallStatus } from './protocol-CZJ1v9Hq.js';
+
+/**
+ * What the mock can be driven to do. There is one scenario per terminal state plus the
+ * interesting mid-stream shapes, because a Storybook that cannot SHOW a state is a Storybook
+ * in which that state is never reviewed — and a test suite that cannot REACH one is a suite
+ * in which it is never asserted.
+ */
+type MockScenarioName = 'happy' | 'grounded' | 'toolApproval' | 'toolAuto' | 'blocked' | 'refused' | 'error' | 'notProvisioned' | 'cancelled' | 'longAnswer' | 'throws';
+interface MockScenario {
+    /** The answer, streamed word by word unless `chunks` overrides it. */
+    text: string;
+    chunks?: string[];
+    status: AgentRunStatus;
+    guarded?: boolean;
+    failureMessage?: string;
+    failureCode?: string;
+    recoverable?: boolean;
+    retryAfterMs?: number;
+    sources?: AgentSource[];
+    /** Emitted mid-stream, before the terminal event. */
+    toolCall?: AgentToolCall;
+    /** When set, the tool resolves itself rather than waiting for host approval. */
+    autoToolResult?: string;
+    suggestions?: string[];
+    thinking?: string;
+    /** Throw from inside the iterator — the failure channel a Promise-shaped seam does not have. */
+    throwsMidStream?: boolean;
+    /** Never becomes available; `send()` still yields a well-formed turn. */
+    unavailable?: boolean;
+}
+declare const mockScenarios: Record<MockScenarioName, MockScenario>;
+
+/** Injectable so tests run at zero delay and Storybook runs at human speed. */
+type Scheduler = (ms: number) => Promise<void>;
+declare const realScheduler: Scheduler;
+declare const immediateScheduler: Scheduler;
+interface MockAgentServiceOptions {
+    scenario?: MockScenarioName;
+    scheduler?: Scheduler;
+    /** Delay before the first token, so the typing indicator is visible and screenshottable. */
+    firstTokenMs?: number;
+    chunkMs?: number;
+    /**
+     * ★ A CONSTRUCTOR ARGUMENT, never module state.
+     *
+     * tsup runs with `splitting: false`, so every entry gets a self-contained bundle and any
+     * module-level `let` is physically duplicated per entry — a story importing from `.` and a
+     * test importing from `./services` would get two independent counters. Measured on
+     * surface-kit: three copies of the same function body across its entries.
+     */
+    seed?: number;
+    /** Override availability; otherwise derived from the scenario. */
+    availability?: AgentAvailability;
+}
+/**
+ * The in-package fake. It is the only "provider" agent-kit ships: real transports (Foundry,
+ * Copilot Studio, a broker) live in the consuming app, so the kit never holds a credential.
+ *
+ * ★ It can reach EVERY `AgentRunStatus`. A test asserts that, because a mock that cannot
+ *   produce a state is a state nothing downstream is ever tested against.
+ */
+declare class MockAgentService implements IAgentService {
+    readonly name = "mock";
+    private readonly scenario;
+    private readonly scenarioName;
+    private readonly scheduler;
+    private readonly firstTokenMs;
+    private readonly chunkMs;
+    private readonly rand;
+    private readonly availabilityOverride?;
+    constructor(options?: MockAgentServiceOptions);
+    isAvailable(): Promise<AgentAvailability>;
+    /**
+     * A prompt can select a scenario (`/blocked`, `/tool`, `/error`), so one story can walk
+     * every state without remounting.
+     */
+    private resolveScenario;
+    send(turn: AgentTurn): AsyncIterable<AgentEvent>;
+}
+
+/**
+ * The default provider: answers nothing, politely.
+ *
+ * ★ `none` is the DEFAULT and must stay so. A kit dropped into a host nobody has wired must
+ *   not silently start talking to a service because someone shipped a new build. Carried
+ *   from `ILlmService`, where the same rule is load-bearing in a regulated process.
+ *
+ * ★ It still yields a well-formed turn — `turn_start` then one `turn_end` — rather than
+ *   throwing or yielding nothing. An unconfigured kit should render "not configured", not
+ *   a spinner that never resolves.
+ */
+declare class NullAgentService implements IAgentService {
+    readonly name = "none";
+    isAvailable(): Promise<AgentAvailability>;
+    send(turn: AgentTurn): AsyncIterable<AgentEvent>;
+}
+
+interface ServiceDecision {
+    provider: IAgentService;
+    /** Why this one was chosen — surfaced in diagnostics so a misconfiguration is legible. */
+    reason: string;
+}
+/**
+ * Provider selection, as ONE ladder.
+ *
+ * ★ `decide()` is exported alongside `createAgentService()` and they share a return type, so
+ *   the factory and any diagnostics view cannot drift — the shape `ServiceFactory.decide()`
+ *   uses in `@dataverse-kit/api-service` for exactly the same reason.
+ *
+ * ★ An UNRECOGNISED provider name falls back to `none`, never to a working provider. Carried
+ *   from `createLlmService`: a typo must produce silence, not an unintended call to a model.
+ */
+declare function decide(config: AgentServiceConfig): ServiceDecision;
+declare function createAgentService(config?: AgentServiceConfig): IAgentService;
+
+export { AgentAvailability, AgentEvent, AgentRunStatus, AgentServiceConfig, AgentSource, AgentToolCall, AgentTurn, IAgentService, MockAgentService, type MockAgentServiceOptions, type MockScenario, type MockScenarioName, NullAgentService, type Scheduler, createAgentService, decide, immediateScheduler, mockScenarios, realScheduler };