@tangle-network/agent-runtime 0.338.0 → 0.339.0

package/dist/placement.js.map

@@ -1 +1 @@
-{"version":3,"file":"placement.js","names":[],"sources":["../src/placement/index.ts"],"sourcesContent":["/**\n * Execution placement: choose the cheapest executor whose declared capabilities\n * cover the work, before any key, sandbox or model call.\n *\n * A pure decision over DECLARED data — the work's requirements and its resolved\n * {@link AgentProfile}. It never reads the prompt and does no I/O, so it is safe\n * in a Worker or Durable Object and costs nothing on the path to the first word.\n * Tiers, cheapest first:\n *  - `inference`: one Router call, when nothing needs a tool, a file or a session;\n *  - `loop`: the Runtime tool loop in the caller's own process (a Worker or the\n *    Platform workflow worker), when the only tools are ones that loop holds;\n *  - `sandbox`: anything that needs a harness, a filesystem, a shell, files, MCP\n *    servers, subagents, hooks or an interactive session.\n * A requirement no tier can meet refuses the work by name\n * ({@link PlacementRefusedError}); a capability is never dropped silently, and a\n * pinned harness always runs in the sandbox.\n *\n * This is Platform's `agent-placement/2` (`selectAgentPlacement` and\n * `workerProfileRefusal`) moved here unchanged in semantics. Its reason strings\n * are kept byte-identical so a shadow comparison against Platform's copy reads\n * equal; only the tier name changes (`worker` → `loop`). `agent-placement/3`\n * adds two caller opt-ins, both off by default:\n *  - {@link PlaceExecutionInput.vacuousAxes}: a deny-only `permissions` map asks\n *    for nothing a tier lacks, so it counts as covered;\n *  - {@link PlaceExecutionInput.inlineSkills}: profile skills count as covered on\n *    `loop` when the caller inlines their content.\n */\n\nimport type { AgentProfile } from '@tangle-network/agent-interface'\nimport type {\n  AgentProfileMaterializationAxis,\n  ProfileMaterializationContract,\n} from '../agent/profile-materialization'\n\n/** The policy version every {@link PlacementRecord} carries. */\nexport const PLACEMENT_POLICY = 'agent-placement/3'\n\n/** Where one unit of agent work runs, cheapest first. */\nexport type ExecutionTier = 'inference' | 'loop' | 'sandbox'\n\n/** What was chosen, under which policy, why, and why each other tier was refused. */\nexport interface PlacementRecord {\n  chosen: ExecutionTier\n  policy: typeof PLACEMENT_POLICY\n  reason: string\n  /**\n   * The profile's declared materialization axes the chosen tier carries. A tier that\n   * cannot carry a declared axis is rejected, so on a fresh decision this is every\n   * declared axis; an authored or resumed record makes no coverage decision and is empty.\n   */\n  coveredAxes: AgentProfileMaterializationAxis[]\n  rejected: Array<{ placement: ExecutionTier; reason: string }>\n}\n\n/**\n * The declared requirements of the work, beside its profile. Field names follow\n * Platform's `agent.run` action, the first consumer; an app's chat turn usually\n * declares none of them.\n */\nexport interface PlacementRequirements {\n  /** A pinned harness. Always runs in the sandbox. */\n  harness?: string\n  /** A model other than the profile's own needs the sandbox to choose between them. */\n  model?: string\n  source?: unknown\n  /** Skill ids resolved into a box. Profile skills are `profile.resources.skills`. */\n  skills?: unknown\n  env?: unknown\n  image?: unknown\n  size?: unknown\n  resources?: unknown\n  fromSnapshot?: unknown\n  fromSandboxId?: unknown\n  resume?: unknown\n  maxRounds?: number\n  ask?: boolean\n  /** Hub connections: tools the loop holds. */\n  connections?: readonly string[]\n  /** Owner-object grants: tools only the loop holds. */\n  objects?: unknown\n  /** Public HTTPS reads: a tool only the loop holds. */\n  http?: unknown\n  /** Tools the caller binds into the loop itself, such as an app's product tools. */\n  tools?: readonly string[]\n}\n\n/** Which tiers this deployment has wired. */\nexport interface PlacementContext {\n  interactive: boolean\n  inferenceAvailable: boolean\n  loopAvailable: boolean\n  /** Why the loop cannot take this work, when it cannot. */\n  loopUnavailableReason?: string\n}\n\n/** Profile axes a tier may count as covered when their declared value grants nothing. */\nexport type VacuousAxis = 'permissions'\n\nexport interface PlaceExecutionInput {\n  requirements?: PlacementRequirements\n  /** The RESOLVED profile: a named profile is read before the decision. */\n  profile?: AgentProfile | object\n  context: PlacementContext\n  /**\n   * Axes whose deny-only value counts as covered on `inference` and `loop`.\n   * `permissions` qualifies when every rule is `deny`: a tier without native tools\n   * already denies them. Deny-only `tools` are covered without opting in.\n   */\n  vacuousAxes?: readonly VacuousAxis[]\n  /**\n   * The caller inlines the profile's skill content into the loop's context, so\n   * `resources.skills` (with a strict `resources.failOnError`) and the native `skill`\n   * tool and permission that load them count as covered on `loop`. Off by default:\n   * the skills then keep the work in the sandbox.\n   */\n  inlineSkills?: boolean\n}\n\n/** No tier can meet every declared requirement. Raised before any spend. */\nexport class PlacementRefusedError extends Error {\n  constructor(readonly reason: string) {\n    super(`placement cannot run this work — ${reason}`)\n    this.name = 'PlacementRefusedError'\n  }\n}\n\n/**\n * The profile axes `inference` and `loop` carry: identity, prompt, model controls and\n * metadata. No harness, native tools, files, MCP, subagents, hooks or modes.\n */\nexport const loopTierProfileMaterialization: ProfileMaterializationContract = {\n  name: 'placement-loop-tier',\n  axes: [\n    'name',\n    'description',\n    'version',\n    'tags',\n    'systemPrompt',\n    'appendSystemPrompt',\n    'instructions',\n    'modelDefault',\n    'modelSmall',\n    'modelProvider',\n    'modelReasoningEffort',\n    'modelMaxVisibleOutputTokens',\n    'modelMaxTotalOutputTokens',\n    'modelMetadata',\n    'metadata',\n  ],\n}\n\n/** Compound profile properties and the axis each child maps to. */\nconst COMPOUND_FIELDS: Record<string, Record<string, AgentProfileMaterializationAxis>> = {\n  prompt: {\n    systemPrompt: 'systemPrompt',\n    appendSystemPrompt: 'appendSystemPrompt',\n    instructions: 'instructions',\n  },\n  model: {\n    default: 'modelDefault',\n    small: 'modelSmall',\n    provider: 'modelProvider',\n    reasoningEffort: 'modelReasoningEffort',\n    maxVisibleOutputTokens: 'modelMaxVisibleOutputTokens',\n    maxReasoningTokens: 'modelMaxReasoningTokens',\n    maxTotalOutputTokens: 'modelMaxTotalOutputTokens',\n    metadata: 'modelMetadata',\n  },\n  resources: {\n    files: 'files',\n    tools: 'resourceTools',\n    skills: 'skills',\n    agents: 'resourceAgents',\n    commands: 'commands',\n    instructions: 'resourceInstructions',\n    failOnError: 'resourceFailOnError',\n  },\n}\n\n/** Top-level profile properties that are themselves an axis (the rest are compounds). */\nconst TOP_LEVEL_AXES: ReadonlySet<string> = new Set([\n  'name',\n  'description',\n  'version',\n  'tags',\n  'harness',\n  'seats',\n  'permissions',\n  'tools',\n  'mcp',\n  'connections',\n  'subagents',\n  'hooks',\n  'modes',\n  'confidential',\n  'metadata',\n  'extensions',\n])\n\n/** Options for {@link loopProfileRefusal}. */\nexport interface LoopProfileRefusalOptions {\n  vacuousAxes?: readonly VacuousAxis[]\n  inlineSkills?: boolean\n}\n\n/**\n * Why `inference` and `loop` cannot run this profile, or undefined when they can.\n * A profile that needs a harness, files, harness built-in tools, MCP servers,\n * subagents, hooks or modes needs a sandbox; the loop never drops one silently.\n * Platform's `workerProfileRefusal`, read through {@link loopTierProfileMaterialization}.\n */\nexport function loopProfileRefusal(\n  profile: object,\n  options: LoopProfileRefusalOptions = {},\n): string | undefined {\n  const fields = profile as Record<string, unknown>\n  const vacuousPermissions = options.vacuousAxes?.includes('permissions') === true\n  const inlineSkills = options.inlineSkills === true\n  const carried = new Set<string>(loopTierProfileMaterialization.axes)\n  if (inlineSkills) carried.add('skills')\n  const childCovered = (field: string, child: string, value: unknown): boolean => {\n    const axis = COMPOUND_FIELDS[field]?.[child]\n    if (axis === undefined) return false\n    // A strict failure policy is honoured by an inliner that fails closed; a best-effort\n    // one would have to report a skipped skill, which the loop has no channel for.\n    if (axis === 'resourceFailOnError') return inlineSkills && value === true\n    return carried.has(axis)\n  }\n  const reasons: string[] = []\n  for (const [field, value] of Object.entries(fields)) {\n    if (value === undefined) continue\n    if (field === 'tools') continue\n    if (\n      field === 'permissions' &&\n      vacuousPermissions &&\n      permissionsGrantNothing(value, inlineSkills)\n    )\n      continue\n    if (TOP_LEVEL_AXES.has(field) && carried.has(field)) continue\n    const children = COMPOUND_FIELDS[field]\n    if (children && Object.values(children).some((axis) => carried.has(axis))) continue\n    reasons.push(`profile ${field} needs a sandbox`)\n  }\n  for (const field of Object.keys(COMPOUND_FIELDS)) {\n    const value = fields[field]\n    if (typeof value !== 'object' || value === null) continue\n    // A compound the loop carries none of was refused whole above.\n    if (!Object.values(COMPOUND_FIELDS[field] ?? {}).some((axis) => carried.has(axis))) continue\n    for (const [child, inner] of Object.entries(value)) {\n      if (inner !== undefined && !childCovered(field, child, inner)) {\n        reasons.push(`profile ${field}.${child} is not supported by the worker`)\n      }\n    }\n  }\n  // Harness built-in tools (shell, edit, browser) exist only in a sandbox. A profile may\n  // still switch them off. The `skill` tool only loads skills, which an inliner supplies.\n  const tools = fields.tools\n  if (typeof tools === 'object' && tools !== null) {\n    const enabled = Object.entries(tools)\n      .filter(([name, on]) => on === true && !(inlineSkills && name === 'skill'))\n      .map(([name]) => name)\n    if (enabled.length > 0) reasons.push(`profile tools ${enabled.join(', ')} need a sandbox`)\n  }\n  return reasons.length > 0 ? reasons.join('; ') : undefined\n}\n\n/** True when every permission rule denies, or allows only `skill` under inlined skills. */\nfunction permissionsGrantNothing(value: unknown, inlineSkills: boolean): boolean {\n  if (typeof value !== 'object' || value === null) return false\n  return Object.entries(value).every(([tool, rule]) => {\n    if (inlineSkills && tool === 'skill') return true\n    if (rule === 'deny') return true\n    if (typeof rule !== 'object' || rule === null) return false\n    return Object.values(rule).every((inner) => inner === 'deny')\n  })\n}\n\n/** Requirement fields that only mean something inside a provisioned box. */\nconst SANDBOX_FIELDS = [\n  'source',\n  'skills',\n  'env',\n  'image',\n  'size',\n  'resources',\n  'fromSnapshot',\n  'fromSandboxId',\n  'resume',\n] as const satisfies ReadonlyArray<keyof PlacementRequirements>\n\ninterface RequirementOptions extends LoopProfileRefusalOptions {\n  requirements: PlacementRequirements\n  profile?: object\n  interactive: boolean\n}\n\n/** Every declared requirement only a sandbox can meet, in field order. */\nfunction sandboxRequirements(options: RequirementOptions): string[] {\n  const { requirements: cfg, profile } = options\n  const needs: string[] = []\n  if (options.interactive) needs.push('interactive run needs a session')\n  if (cfg.harness !== undefined) needs.push(`harness ${cfg.harness} is pinned`)\n  for (const field of SANDBOX_FIELDS) {\n    if (cfg[field] !== undefined) needs.push(`${field} needs a sandbox`)\n  }\n  if (cfg.maxRounds !== undefined && cfg.maxRounds > 1)\n    needs.push('maxRounds > 1 needs a multi-round session')\n  if (cfg.ask === true) needs.push('ask needs a session to answer into')\n  const refusal = profile ? loopProfileRefusal(profile, options) : undefined\n  if (refusal) needs.push(refusal)\n  // Inference and the loop run the profile's own model and refuse another; only the\n  // sandbox decides between a requested model and the profile's.\n  const profileModel = profileDefaultModel(profile)\n  if (cfg.model !== undefined && profileModel !== undefined && cfg.model !== profileModel) {\n    needs.push(\n      `the action model ${cfg.model} differs from the profile model ${String(profileModel)}`,\n    )\n  }\n  return needs\n}\n\nfunction profileDefaultModel(profile: object | undefined): unknown {\n  return (profile as { model?: { default?: unknown } } | undefined)?.model?.default\n}\n\n/** Options for {@link sandboxOnlyRequirements}. */\nexport interface SandboxOnlyRequirementsOptions extends LoopProfileRefusalOptions {\n  requirements?: PlacementRequirements\n  profile?: AgentProfile | object\n  interactive: boolean\n}\n\n/**\n * Every declared requirement only a sandbox can meet. A caller resuming work in the\n * loop it began in checks this is empty before it continues there.\n */\nexport function sandboxOnlyRequirements(options: SandboxOnlyRequirementsOptions): string[] {\n  return sandboxRequirements({ ...options, requirements: options.requirements ?? {} })\n}\n\n/** Tools the work grants, each of which the loop can hold. */\nfunction toolRequirements(cfg: PlacementRequirements): string[] {\n  const tools: string[] = []\n  if ((cfg.connections ?? []).length > 0) tools.push('connections need Hub tools')\n  if (cfg.objects !== undefined) tools.push('objects need object tools')\n  if (cfg.http !== undefined) tools.push('http needs a fetch tool')\n  if ((cfg.tools ?? []).length > 0) tools.push(`tools ${cfg.tools?.join(', ')} need the loop`)\n  return tools\n}\n\n/** Grants only the loop holds: a sandbox cannot honour them. */\nfunction loopOnlyGrants(cfg: PlacementRequirements): string[] {\n  return [\n    ...(cfg.objects !== undefined ? ['objects'] : []),\n    ...(cfg.http !== undefined ? ['http'] : []),\n  ]\n}\n\n/** True when the profile declares skills that only an inliner on the loop can carry. */\nfunction declaresProfileSkills(profile: object | undefined): boolean {\n  const fields = (profile ?? {}) as {\n    resources?: { skills?: unknown }\n    tools?: Record<string, unknown>\n    permissions?: Record<string, unknown>\n  }\n  const skills = fields.resources?.skills\n  return (\n    (Array.isArray(skills) && skills.length > 0) ||\n    fields.tools?.skill === true ||\n    (fields.permissions?.skill !== undefined && fields.permissions.skill !== 'deny')\n  )\n}\n\n/**\n * Choose where work runs: the cheapest tier every declared requirement allows.\n * Throws {@link PlacementRefusedError} when no tier can meet every requirement.\n */\nexport function placeExecution(input: PlaceExecutionInput): PlacementRecord {\n  const cfg = input.requirements ?? {}\n  const { context, profile } = input\n  const opts: LoopProfileRefusalOptions = {\n    ...(input.vacuousAxes ? { vacuousAxes: input.vacuousAxes } : {}),\n    ...(input.inlineSkills ? { inlineSkills: true } : {}),\n  }\n  const sandboxNeeds = sandboxRequirements({\n    requirements: cfg,\n    profile,\n    interactive: context.interactive,\n    ...opts,\n  })\n  const tools = toolRequirements(cfg)\n  if (input.inlineSkills && declaresProfileSkills(profile))\n    tools.push('skills are inlined by the loop')\n  const loopOnly = loopOnlyGrants(cfg)\n  const coveredAxes = profile ? declaredAxes(profile) : []\n  const record = (\n    chosen: ExecutionTier,\n    reason: string,\n    rejected: PlacementRecord['rejected'],\n  ): PlacementRecord => ({ chosen, policy: PLACEMENT_POLICY, reason, coveredAxes, rejected })\n\n  if (sandboxNeeds.length > 0) {\n    const reason = sandboxNeeds.join('; ')\n    if (loopOnly.length > 0) {\n      throw new PlacementRefusedError(\n        `${loopOnly.join(' and ')} run only in the worker, but ${reason}`,\n      )\n    }\n    return record('sandbox', reason, [\n      { placement: 'inference', reason },\n      { placement: 'loop', reason },\n    ])\n  }\n\n  // Past the sandbox check the profile is one the loop (and a single Router call) can\n  // honour, so only granted tools separate the two.\n  if (tools.length > 0) {\n    const reason = `${tools.join('; ')}, which the worker holds without a sandbox`\n    if (!context.loopAvailable) {\n      const unavailable =\n        context.loopUnavailableReason ?? 'worker placement is not wired on this deployment'\n      if (loopOnly.length > 0) {\n        throw new PlacementRefusedError(\n          `${loopOnly.join(' and ')} need the worker, but ${unavailable}`,\n        )\n      }\n      // Inlined skills are the one loop need a sandbox also meets, natively.\n      return record('sandbox', unavailable, [\n        { placement: 'inference', reason: tools.join('; ') },\n        { placement: 'loop', reason: unavailable },\n      ])\n    }\n    return record('loop', reason, [\n      { placement: 'inference', reason: tools.join('; ') },\n      { placement: 'sandbox', reason: 'costs more and no declared requirement needs it' },\n    ])\n  }\n\n  if (context.inferenceAvailable) {\n    return record('inference', 'no declared requirement needs tools, files or a session', [\n      { placement: 'loop', reason: 'no declared tool needs a loop' },\n      { placement: 'sandbox', reason: 'costs more and no declared requirement needs it' },\n    ])\n  }\n  const unwired = 'inference is not wired on this deployment'\n  if (context.loopAvailable) {\n    return record('loop', `${unwired}; one tool-free worker turn`, [\n      { placement: 'inference', reason: unwired },\n      { placement: 'sandbox', reason: 'costs more and no declared requirement needs it' },\n    ])\n  }\n  return record('sandbox', unwired, [\n    { placement: 'inference', reason: unwired },\n    { placement: 'loop', reason: 'worker placement is not wired on this deployment' },\n  ])\n}\n\n/** The materialization axes a profile declares, in its own field order. Read from the\n *  same field map as {@link loopProfileRefusal}, so the module has no runtime import. */\nfunction declaredAxes(profile: object): AgentProfileMaterializationAxis[] {\n  const axes: AgentProfileMaterializationAxis[] = []\n  for (const [field, value] of Object.entries(profile)) {\n    if (value === undefined) continue\n    if (TOP_LEVEL_AXES.has(field)) axes.push(field as AgentProfileMaterializationAxis)\n    const children = COMPOUND_FIELDS[field]\n    if (!children || typeof value !== 'object' || value === null) continue\n    for (const [child, inner] of Object.entries(value)) {\n      const axis = children[child]\n      if (axis !== undefined && inner !== undefined) axes.push(axis)\n    }\n  }\n  return axes\n}\n\n/** The record for a tier the author named: nothing was chosen or refused. */\nexport function authoredPlacement(chosen: ExecutionTier): PlacementRecord {\n  return {\n    chosen,\n    policy: PLACEMENT_POLICY,\n    reason: `authored placement: ${chosen}`,\n    coveredAxes: [],\n    rejected: [],\n  }\n}\n\n/**\n * The record for work that resumes under the tier it began with. A retry reuses the\n * recorded tier and never re-decides, so one turn never runs on two tiers; a caller\n * resuming on `loop` first checks {@link sandboxOnlyRequirements} is empty.\n */\nexport function resumedPlacement(chosen: ExecutionTier): PlacementRecord {\n  return {\n    chosen,\n    policy: PLACEMENT_POLICY,\n    reason: `resumed under the placement it began with: ${chosen}`,\n    coveredAxes: [],\n    rejected: [],\n  }\n}\n"],"mappings":"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"}
+{"version":3,"file":"placement.js","names":[],"sources":["../src/placement/index.ts"],"sourcesContent":["/**\n * Execution placement: choose the cheapest executor whose declared capabilities\n * cover the work, before any key, sandbox or model call.\n *\n * A pure decision over DECLARED data — the work's requirements and its resolved\n * {@link AgentProfile}. It never reads the prompt and does no I/O, so it is safe\n * in a Worker or Durable Object and costs nothing on the path to the first word.\n * Tiers, cheapest first:\n *  - `inference`: one Router call, when nothing needs a tool, a file or a session;\n *  - `loop`: the Runtime tool loop in the caller's own process (a Worker or the\n *    Platform workflow worker), when the only tools are ones that loop holds;\n *  - `sandbox`: anything that needs a harness, a filesystem, a shell, files, MCP\n *    servers, subagents, hooks or an interactive session.\n * A requirement no tier can meet refuses the work by name\n * ({@link PlacementRefusedError}); a capability is never dropped silently, and a\n * pinned harness always runs in the sandbox.\n *\n * This is Platform's `agent-placement/2` (`selectAgentPlacement` and\n * `workerProfileRefusal`) moved here unchanged in semantics. Its reason strings\n * are kept byte-identical so a shadow comparison against Platform's copy reads\n * equal; only the tier name changes (`worker` → `loop`). `agent-placement/3`\n * adds two caller opt-ins, both off by default:\n *  - {@link PlaceExecutionInput.vacuousAxes}: a deny-only `permissions` map asks\n *    for nothing a tier lacks, so it counts as covered;\n *  - {@link PlaceExecutionInput.inlineSkills}: profile skills count as covered on\n *    `loop` when the caller inlines their content.\n */\n\nimport type { AgentProfile } from '@tangle-network/agent-interface'\nimport type {\n  AgentProfileMaterializationAxis,\n  ProfileMaterializationContract,\n} from '../agent/profile-materialization'\n\n/** The policy version every {@link PlacementRecord} carries. */\nexport const PLACEMENT_POLICY = 'agent-placement/3'\n\n/** Where one unit of agent work runs, cheapest first. */\nexport type ExecutionTier = 'inference' | 'loop' | 'sandbox'\n\n/** What was chosen, under which policy, why, and why each other tier was refused. */\nexport interface PlacementRecord {\n  chosen: ExecutionTier\n  policy: typeof PLACEMENT_POLICY\n  reason: string\n  /**\n   * The profile's declared materialization axes the chosen tier carries. A tier that\n   * cannot carry a declared axis is rejected, so on a fresh decision this is every\n   * declared axis; an authored or resumed record makes no coverage decision and is empty.\n   */\n  coveredAxes: AgentProfileMaterializationAxis[]\n  rejected: Array<{ placement: ExecutionTier; reason: string }>\n}\n\n/**\n * The declared requirements of the work, beside its profile. Field names follow\n * Platform's `agent.run` action, the first consumer; an app's chat turn usually\n * declares none of them.\n */\nexport interface PlacementRequirements {\n  /** A pinned harness. Always runs in the sandbox. */\n  harness?: string\n  /** A model other than the profile's own needs the sandbox to choose between them. */\n  model?: string\n  source?: unknown\n  /** Skill ids resolved into a box. Profile skills are `profile.resources.skills`. */\n  skills?: unknown\n  env?: unknown\n  image?: unknown\n  size?: unknown\n  resources?: unknown\n  fromSnapshot?: unknown\n  fromSandboxId?: unknown\n  resume?: unknown\n  maxRounds?: number\n  ask?: boolean\n  /** Hub connections: tools the loop holds. */\n  connections?: readonly string[]\n  /** Owner-object grants: tools only the loop holds. */\n  objects?: unknown\n  /** Public HTTPS reads: a tool only the loop holds. */\n  http?: unknown\n  /** Tools the caller binds into the loop itself, such as an app's product tools. */\n  tools?: readonly string[]\n}\n\n/** Which tiers this deployment has wired. */\nexport interface PlacementContext {\n  interactive: boolean\n  inferenceAvailable: boolean\n  loopAvailable: boolean\n  /** Why the loop cannot take this work, when it cannot. */\n  loopUnavailableReason?: string\n}\n\n/** Profile axes a tier may count as covered when their declared value grants nothing. */\nexport type VacuousAxis = 'permissions'\n\nexport interface PlaceExecutionInput {\n  requirements?: PlacementRequirements\n  /** The RESOLVED profile: a named profile is read before the decision. */\n  profile?: AgentProfile | object\n  context: PlacementContext\n  /**\n   * Axes whose deny-only value counts as covered on `inference` and `loop`.\n   * `permissions` qualifies when every rule is `deny`: a tier without native tools\n   * already denies them. Deny-only `tools` are covered without opting in.\n   */\n  vacuousAxes?: readonly VacuousAxis[]\n  /**\n   * The caller inlines the profile's skill content into the loop's context, so\n   * `resources.skills` (with a strict `resources.failOnError`) and the native `skill`\n   * tool and permission that load them count as covered on `loop`. Off by default:\n   * the skills then keep the work in the sandbox.\n   */\n  inlineSkills?: boolean\n}\n\n/** No tier can meet every declared requirement. Raised before any spend. */\nexport class PlacementRefusedError extends Error {\n  constructor(readonly reason: string) {\n    super(`placement cannot run this work — ${reason}`)\n    this.name = 'PlacementRefusedError'\n  }\n}\n\n/**\n * The profile axes `inference` and `loop` carry: identity, prompt, model controls and\n * metadata. No harness, native tools, files, MCP, subagents, hooks or modes.\n */\nexport const loopTierProfileMaterialization: ProfileMaterializationContract = {\n  name: 'placement-loop-tier',\n  axes: [\n    'name',\n    'description',\n    'version',\n    'tags',\n    'systemPrompt',\n    'appendSystemPrompt',\n    'instructions',\n    'modelDefault',\n    'modelSmall',\n    'modelProvider',\n    'modelReasoningEffort',\n    'modelMaxVisibleOutputTokens',\n    'modelMaxTotalOutputTokens',\n    'modelMetadata',\n    'metadata',\n  ],\n}\n\n/** Compound profile properties and the axis each child maps to. */\nconst COMPOUND_FIELDS: Record<string, Record<string, AgentProfileMaterializationAxis>> = {\n  prompt: {\n    systemPrompt: 'systemPrompt',\n    appendSystemPrompt: 'appendSystemPrompt',\n    instructions: 'instructions',\n  },\n  model: {\n    default: 'modelDefault',\n    small: 'modelSmall',\n    provider: 'modelProvider',\n    reasoningEffort: 'modelReasoningEffort',\n    maxVisibleOutputTokens: 'modelMaxVisibleOutputTokens',\n    maxReasoningTokens: 'modelMaxReasoningTokens',\n    maxTotalOutputTokens: 'modelMaxTotalOutputTokens',\n    metadata: 'modelMetadata',\n  },\n  resources: {\n    files: 'files',\n    tools: 'resourceTools',\n    skills: 'skills',\n    agents: 'resourceAgents',\n    commands: 'commands',\n    instructions: 'resourceInstructions',\n    failOnError: 'resourceFailOnError',\n  },\n}\n\n/** Top-level profile properties that are themselves an axis (the rest are compounds). */\nconst TOP_LEVEL_AXES: ReadonlySet<string> = new Set([\n  'name',\n  'description',\n  'version',\n  'tags',\n  'harness',\n  'seats',\n  'permissions',\n  'tools',\n  'mcp',\n  'connections',\n  'subagents',\n  'hooks',\n  'modes',\n  'confidential',\n  'metadata',\n  'extensions',\n])\n\n/** Options for {@link loopProfileRefusal}. */\ninterface LoopProfileRefusalOptions {\n  vacuousAxes?: readonly VacuousAxis[]\n  inlineSkills?: boolean\n}\n\n/**\n * Why `inference` and `loop` cannot run this profile, or undefined when they can.\n * A profile that needs a harness, files, harness built-in tools, MCP servers,\n * subagents, hooks or modes needs a sandbox; the loop never drops one silently.\n * Platform's `workerProfileRefusal`, read through {@link loopTierProfileMaterialization}.\n */\nfunction loopProfileRefusal(\n  profile: object,\n  options: LoopProfileRefusalOptions = {},\n): string | undefined {\n  const fields = profile as Record<string, unknown>\n  const vacuousPermissions = options.vacuousAxes?.includes('permissions') === true\n  const inlineSkills = options.inlineSkills === true\n  const carried = new Set<string>(loopTierProfileMaterialization.axes)\n  if (inlineSkills) carried.add('skills')\n  const childCovered = (field: string, child: string, value: unknown): boolean => {\n    const axis = COMPOUND_FIELDS[field]?.[child]\n    if (axis === undefined) return false\n    // A strict failure policy is honoured by an inliner that fails closed; a best-effort\n    // one would have to report a skipped skill, which the loop has no channel for.\n    if (axis === 'resourceFailOnError') return inlineSkills && value === true\n    return carried.has(axis)\n  }\n  const reasons: string[] = []\n  for (const [field, value] of Object.entries(fields)) {\n    if (value === undefined) continue\n    if (field === 'tools') continue\n    if (\n      field === 'permissions' &&\n      vacuousPermissions &&\n      permissionsGrantNothing(value, inlineSkills)\n    )\n      continue\n    if (TOP_LEVEL_AXES.has(field) && carried.has(field)) continue\n    const children = COMPOUND_FIELDS[field]\n    if (children && Object.values(children).some((axis) => carried.has(axis))) continue\n    reasons.push(`profile ${field} needs a sandbox`)\n  }\n  for (const field of Object.keys(COMPOUND_FIELDS)) {\n    const value = fields[field]\n    if (typeof value !== 'object' || value === null) continue\n    // A compound the loop carries none of was refused whole above.\n    if (!Object.values(COMPOUND_FIELDS[field] ?? {}).some((axis) => carried.has(axis))) continue\n    for (const [child, inner] of Object.entries(value)) {\n      if (inner !== undefined && !childCovered(field, child, inner)) {\n        reasons.push(`profile ${field}.${child} is not supported by the worker`)\n      }\n    }\n  }\n  // Harness built-in tools (shell, edit, browser) exist only in a sandbox. A profile may\n  // still switch them off. The `skill` tool only loads skills, which an inliner supplies.\n  const tools = fields.tools\n  if (typeof tools === 'object' && tools !== null) {\n    const enabled = Object.entries(tools)\n      .filter(([name, on]) => on === true && !(inlineSkills && name === 'skill'))\n      .map(([name]) => name)\n    if (enabled.length > 0) reasons.push(`profile tools ${enabled.join(', ')} need a sandbox`)\n  }\n  return reasons.length > 0 ? reasons.join('; ') : undefined\n}\n\n/** True when every permission rule denies, or allows only `skill` under inlined skills. */\nfunction permissionsGrantNothing(value: unknown, inlineSkills: boolean): boolean {\n  if (typeof value !== 'object' || value === null) return false\n  return Object.entries(value).every(([tool, rule]) => {\n    if (inlineSkills && tool === 'skill') return true\n    if (rule === 'deny') return true\n    if (typeof rule !== 'object' || rule === null) return false\n    return Object.values(rule).every((inner) => inner === 'deny')\n  })\n}\n\n/** Requirement fields that only mean something inside a provisioned box. */\nconst SANDBOX_FIELDS = [\n  'source',\n  'skills',\n  'env',\n  'image',\n  'size',\n  'resources',\n  'fromSnapshot',\n  'fromSandboxId',\n  'resume',\n] as const satisfies ReadonlyArray<keyof PlacementRequirements>\n\ninterface RequirementOptions extends LoopProfileRefusalOptions {\n  requirements: PlacementRequirements\n  profile?: object\n  interactive: boolean\n}\n\n/** Every declared requirement only a sandbox can meet, in field order. */\nfunction sandboxRequirements(options: RequirementOptions): string[] {\n  const { requirements: cfg, profile } = options\n  const needs: string[] = []\n  if (options.interactive) needs.push('interactive run needs a session')\n  if (cfg.harness !== undefined) needs.push(`harness ${cfg.harness} is pinned`)\n  for (const field of SANDBOX_FIELDS) {\n    if (cfg[field] !== undefined) needs.push(`${field} needs a sandbox`)\n  }\n  if (cfg.maxRounds !== undefined && cfg.maxRounds > 1)\n    needs.push('maxRounds > 1 needs a multi-round session')\n  if (cfg.ask === true) needs.push('ask needs a session to answer into')\n  const refusal = profile ? loopProfileRefusal(profile, options) : undefined\n  if (refusal) needs.push(refusal)\n  // Inference and the loop run the profile's own model and refuse another; only the\n  // sandbox decides between a requested model and the profile's.\n  const profileModel = profileDefaultModel(profile)\n  if (cfg.model !== undefined && profileModel !== undefined && cfg.model !== profileModel) {\n    needs.push(\n      `the action model ${cfg.model} differs from the profile model ${String(profileModel)}`,\n    )\n  }\n  return needs\n}\n\nfunction profileDefaultModel(profile: object | undefined): unknown {\n  return (profile as { model?: { default?: unknown } } | undefined)?.model?.default\n}\n\n/** Options for {@link sandboxOnlyRequirements}. */\nexport interface SandboxOnlyRequirementsOptions extends LoopProfileRefusalOptions {\n  requirements?: PlacementRequirements\n  profile?: AgentProfile | object\n  interactive: boolean\n}\n\n/**\n * Every declared requirement only a sandbox can meet. A caller resuming work in the\n * loop it began in checks this is empty before it continues there.\n */\nexport function sandboxOnlyRequirements(options: SandboxOnlyRequirementsOptions): string[] {\n  return sandboxRequirements({ ...options, requirements: options.requirements ?? {} })\n}\n\n/** Tools the work grants, each of which the loop can hold. */\nfunction toolRequirements(cfg: PlacementRequirements): string[] {\n  const tools: string[] = []\n  if ((cfg.connections ?? []).length > 0) tools.push('connections need Hub tools')\n  if (cfg.objects !== undefined) tools.push('objects need object tools')\n  if (cfg.http !== undefined) tools.push('http needs a fetch tool')\n  if ((cfg.tools ?? []).length > 0) tools.push(`tools ${cfg.tools?.join(', ')} need the loop`)\n  return tools\n}\n\n/** Grants only the loop holds: a sandbox cannot honour them. */\nfunction loopOnlyGrants(cfg: PlacementRequirements): string[] {\n  return [\n    ...(cfg.objects !== undefined ? ['objects'] : []),\n    ...(cfg.http !== undefined ? ['http'] : []),\n  ]\n}\n\n/** True when the profile declares skills that only an inliner on the loop can carry. */\nfunction declaresProfileSkills(profile: object | undefined): boolean {\n  const fields = (profile ?? {}) as {\n    resources?: { skills?: unknown }\n    tools?: Record<string, unknown>\n    permissions?: Record<string, unknown>\n  }\n  const skills = fields.resources?.skills\n  return (\n    (Array.isArray(skills) && skills.length > 0) ||\n    fields.tools?.skill === true ||\n    (fields.permissions?.skill !== undefined && fields.permissions.skill !== 'deny')\n  )\n}\n\n/**\n * Choose where work runs: the cheapest tier every declared requirement allows.\n * Throws {@link PlacementRefusedError} when no tier can meet every requirement.\n */\nexport function placeExecution(input: PlaceExecutionInput): PlacementRecord {\n  const cfg = input.requirements ?? {}\n  const { context, profile } = input\n  const opts: LoopProfileRefusalOptions = {\n    ...(input.vacuousAxes ? { vacuousAxes: input.vacuousAxes } : {}),\n    ...(input.inlineSkills ? { inlineSkills: true } : {}),\n  }\n  const sandboxNeeds = sandboxRequirements({\n    requirements: cfg,\n    profile,\n    interactive: context.interactive,\n    ...opts,\n  })\n  const tools = toolRequirements(cfg)\n  if (input.inlineSkills && declaresProfileSkills(profile))\n    tools.push('skills are inlined by the loop')\n  const loopOnly = loopOnlyGrants(cfg)\n  const coveredAxes = profile ? declaredAxes(profile) : []\n  const record = (\n    chosen: ExecutionTier,\n    reason: string,\n    rejected: PlacementRecord['rejected'],\n  ): PlacementRecord => ({ chosen, policy: PLACEMENT_POLICY, reason, coveredAxes, rejected })\n\n  if (sandboxNeeds.length > 0) {\n    const reason = sandboxNeeds.join('; ')\n    if (loopOnly.length > 0) {\n      throw new PlacementRefusedError(\n        `${loopOnly.join(' and ')} run only in the worker, but ${reason}`,\n      )\n    }\n    return record('sandbox', reason, [\n      { placement: 'inference', reason },\n      { placement: 'loop', reason },\n    ])\n  }\n\n  // Past the sandbox check the profile is one the loop (and a single Router call) can\n  // honour, so only granted tools separate the two.\n  if (tools.length > 0) {\n    const reason = `${tools.join('; ')}, which the worker holds without a sandbox`\n    if (!context.loopAvailable) {\n      const unavailable =\n        context.loopUnavailableReason ?? 'worker placement is not wired on this deployment'\n      if (loopOnly.length > 0) {\n        throw new PlacementRefusedError(\n          `${loopOnly.join(' and ')} need the worker, but ${unavailable}`,\n        )\n      }\n      // Inlined skills are the one loop need a sandbox also meets, natively.\n      return record('sandbox', unavailable, [\n        { placement: 'inference', reason: tools.join('; ') },\n        { placement: 'loop', reason: unavailable },\n      ])\n    }\n    return record('loop', reason, [\n      { placement: 'inference', reason: tools.join('; ') },\n      { placement: 'sandbox', reason: 'costs more and no declared requirement needs it' },\n    ])\n  }\n\n  if (context.inferenceAvailable) {\n    return record('inference', 'no declared requirement needs tools, files or a session', [\n      { placement: 'loop', reason: 'no declared tool needs a loop' },\n      { placement: 'sandbox', reason: 'costs more and no declared requirement needs it' },\n    ])\n  }\n  const unwired = 'inference is not wired on this deployment'\n  if (context.loopAvailable) {\n    return record('loop', `${unwired}; one tool-free worker turn`, [\n      { placement: 'inference', reason: unwired },\n      { placement: 'sandbox', reason: 'costs more and no declared requirement needs it' },\n    ])\n  }\n  return record('sandbox', unwired, [\n    { placement: 'inference', reason: unwired },\n    { placement: 'loop', reason: 'worker placement is not wired on this deployment' },\n  ])\n}\n\n/** The materialization axes a profile declares, in its own field order. Read from the\n *  same field map as {@link loopProfileRefusal}, so the module has no runtime import. */\nfunction declaredAxes(profile: object): AgentProfileMaterializationAxis[] {\n  const axes: AgentProfileMaterializationAxis[] = []\n  for (const [field, value] of Object.entries(profile)) {\n    if (value === undefined) continue\n    if (TOP_LEVEL_AXES.has(field)) axes.push(field as AgentProfileMaterializationAxis)\n    const children = COMPOUND_FIELDS[field]\n    if (!children || typeof value !== 'object' || value === null) continue\n    for (const [child, inner] of Object.entries(value)) {\n      const axis = children[child]\n      if (axis !== undefined && inner !== undefined) axes.push(axis)\n    }\n  }\n  return axes\n}\n\n/** The record for a tier the author named: nothing was chosen or refused. */\nexport function authoredPlacement(chosen: ExecutionTier): PlacementRecord {\n  return {\n    chosen,\n    policy: PLACEMENT_POLICY,\n    reason: `authored placement: ${chosen}`,\n    coveredAxes: [],\n    rejected: [],\n  }\n}\n\n/**\n * The record for work that resumes under the tier it began with. A retry reuses the\n * recorded tier and never re-decides, so one turn never runs on two tiers; a caller\n * resuming on `loop` first checks {@link sandboxOnlyRequirements} is empty.\n */\nexport function resumedPlacement(chosen: ExecutionTier): PlacementRecord {\n  return {\n    chosen,\n    policy: PLACEMENT_POLICY,\n    reason: `resumed under the placement it began with: ${chosen}`,\n    coveredAxes: [],\n    rejected: [],\n  }\n}\nexport type {\n  AgentProfileMaterializationAxis,\n  KnownAgentProfileMaterializationAxis,\n} from '../agent/profile-materialization'\n"],"mappings":"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"}

package/dist/platform.d.ts

@@ -1,4 +1,3 @@
-import { a as HealthCheck, c as PlatformCatalogProvider, d as PlatformHubClientOptions, f as PlatformHubError, h as StartAuthResult, i as ExecInput, l as PlatformConnection, m as StartAuthInput, n as ConnectionHealth, o as MintTokenInput, p as PlatformHubStatus, r as ConnectionHealthResult, s as MintTokenResult, t as CatalogResult, u as PlatformHubClient } from "./integrations-6xttbPi9.js";
 //#region src/platform/auth.d.ts
 /**
  * Server-side client for the Tangle platform's cross-site SSO bridge.
@@ -73,6 +72,194 @@ declare class PlatformAuthClient {
   exchange(code: string): Promise<ExchangeCodeResult>;
 }
 //#endregion
+//#region src/platform/integrations.d.ts
+/**
+ * Server-side client for the Tangle platform's integration hub
+ * (`/v1/hub/*`). Consumer apps use this instead of rolling their own
+ * OAuth + connection tables.
+ *
+ * Auth: the caller supplies a bearer (either the user's API key from
+ * cross-site exchange, or a platform service token) on construction.
+ *
+ * Endpoint contract (authoritative): the platform API's hub contract
+ * and hub route (both in agent-container's platform API). The platform wraps every response in
+ * `{ success, data }`; non-2xx or `success:false` surfaces as `PlatformHubError`
+ * carrying the real upstream status.
+ */
+interface PlatformHubClientOptions {
+  /** Platform base URL, e.g. `https://id.tangle.tools`. */
+  baseUrl: string;
+  /** Bearer credential — user API key or service token. */
+  bearer: string;
+  /** Override fetch (tests + edge runtimes). */
+  fetchImpl?: typeof fetch;
+}
+/** A live integration connection, as returned by `/v1/hub/connections`. */
+interface PlatformConnection {
+  id: string;
+  providerId: string;
+  displayName: string;
+  accountDisplay: string | null;
+  scopes: string[];
+  status: 'active' | 'revoked' | 'unhealthy' | 'reconnect_required' | (string & {});
+  health: 'unknown' | 'healthy' | 'unhealthy' | 'rate_limited' | (string & {});
+  createdAt: string;
+  updatedAt: string;
+  lastUsedAt: string | null;
+}
+/** A connectable provider in the catalog (`/v1/hub/providers`). */
+interface PlatformCatalogProvider {
+  providerId: string;
+  title?: string;
+  authKind?: string;
+  category?: string;
+  scopes?: string[];
+  capabilityCount?: number;
+  native?: boolean;
+  /** Whether the OAuth app's credentials are wired — the UI offers Connect
+   *  only when true. */
+  configured?: boolean;
+  [k: string]: unknown;
+}
+interface CatalogResult {
+  providers: PlatformCatalogProvider[];
+  /** Count of substrate-bundled connectors behind the catalog. */
+  substrateBundled?: number;
+  [k: string]: unknown;
+}
+interface StartAuthInput {
+  /** The provider to connect (goes in the URL path). */
+  providerId: string;
+  /** Accepted for interface compatibility; the platform's start endpoint is
+   *  provider-level and does not consume a connector id. */
+  connectorId?: string;
+  /** Where the platform redirects the user back to after OAuth. */
+  returnUrl: string;
+  /** Accepted for interface compatibility; not consumed by the start endpoint. */
+  requestedScopes?: string[];
+  /** CLI flow flag — affects the platform's post-auth redirect handling. */
+  cli?: boolean;
+}
+interface StartAuthResult {
+  /** The URL to send the user to. Normalized across the platform's two start
+   *  branches: github returns `authorizationUrl`, substrate returns
+   *  `redirectUrl`. */
+  authorizationUrl: string;
+  state: string;
+  expiresAt?: string;
+  scopes?: string[];
+}
+interface ConnectionHealth {
+  status: 'unknown' | 'healthy' | 'unhealthy' | 'rate_limited' | (string & {});
+  checkedAt: string;
+  error?: {
+    code: string;
+    message: string;
+  };
+}
+interface ConnectionHealthResult {
+  connection: PlatformConnection;
+  health: ConnectionHealth;
+}
+/** Last-known health for a connection, derived from the connection row. */
+interface HealthCheck {
+  connectionId: string;
+  providerId: string;
+  /** Mirrors `PlatformConnection.health`. */
+  status: ConnectionHealth['status'];
+  checkedAt?: string;
+}
+interface MintTokenInput {
+  /** The hub action the token authorizes (e.g. `slack.chat.postMessage`). */
+  actionPath: string;
+  /** Bind to a specific connection, or … */
+  connectionId?: string;
+  /** … resolve the connection by provider for the calling user. */
+  provider?: string;
+}
+interface MintTokenResult {
+  tokenId: string;
+  token: string;
+  expiresAt: string;
+}
+interface ExecInput {
+  /** The hub action path to execute. */
+  path: string;
+  input?: unknown;
+  connectionId?: string;
+}
+interface PlatformHubStatus {
+  contract?: unknown;
+  principal: {
+    kind: string;
+    userId: string;
+    [k: string]: unknown;
+  };
+  connections: {
+    connectedProviderCount: number;
+    unhealthyProviderCount: number;
+  };
+}
+/** Thrown when a `PlatformHubClient` request returns a non-success status. */
+declare class PlatformHubError extends Error {
+  readonly status: number;
+  readonly code: string | undefined;
+  readonly body: unknown;
+  constructor(message: string, status: number, code: string | undefined, body: unknown);
+}
+/** HTTP client for the Tangle Platform Hub API: provider catalog, connection flow, and status. */
+declare class PlatformHubClient {
+  private readonly baseUrl;
+  private readonly bearer;
+  private readonly fetchImpl;
+  constructor(options: PlatformHubClientOptions);
+  /** GET /v1/hub/providers — the connectable provider catalog. */
+  catalog(): Promise<CatalogResult>;
+  /** GET /v1/hub/connections — the calling user's live connections. */
+  listConnections(): Promise<PlatformConnection[]>;
+  /** DELETE /v1/hub/connections/:connectionId — revoke + disable a connection. */
+  revokeConnection(connectionId: string): Promise<{
+    connection: PlatformConnection;
+  }>;
+  /**
+   * POST /v1/hub/connections/:provider/start — begin OAuth/grant. The provider
+   * is taken from the URL; the body carries `returnUrl` (+ `cli`). The platform's
+   * two start branches name the URL field differently (github → `authorizationUrl`,
+   * substrate → `redirectUrl`); this normalizes to `authorizationUrl`.
+   */
+  startAuth(input: StartAuthInput): Promise<StartAuthResult>;
+  /**
+   * Last-known health for every connection. The platform has no global
+   * healthcheck listing — health rides on each connection row — so this derives
+   * the list from `listConnections()` (one request, no extra round-trips).
+   */
+  listHealthchecks(): Promise<HealthCheck[]>;
+  /**
+   * POST /v1/hub/connections/:connectionId/health — trigger a fresh health
+   * probe for one connection and return its updated state.
+   */
+  checkConnectionHealth(connectionId: string): Promise<ConnectionHealthResult>;
+  /**
+   * Trigger a fresh health probe across all of the user's connections. The
+   * platform exposes health per-connection only, so this fans out over
+   * `listConnections()`. `scheduled` is the number of probes dispatched.
+   */
+  runHealthchecks(): Promise<{
+    scheduled: number;
+  }>;
+  /** GET /v1/hub/status — principal + aggregate connection counts. */
+  status(): Promise<PlatformHubStatus>;
+  /**
+   * POST /v1/hub/tokens — mint a short-lived, action-scoped capability token a
+   * sandbox can use to invoke one hub action on the user's behalf without
+   * seeing the underlying provider credential.
+   */
+  mintToken(input: MintTokenInput): Promise<MintTokenResult>;
+  /** POST /v1/hub/exec — execute a hub action and return its result. */
+  exec(input: ExecInput): Promise<unknown>;
+  private request;
+}
+//#endregion
 //#region src/platform/oidc.d.ts
 /**
  * OpenID Connect client for the Tangle authorization server. Identity tokens

package/dist/platform.js

@@ -1,5 +1,4 @@
 import { t as isRecord } from "./record-value-B6bwJxLa.js";
-import { n as PlatformHubError, t as PlatformHubClient } from "./integrations-dFi-ALk7.js";
 //#region src/platform/auth.ts
 /**
 * Server-side client for the Tangle platform's cross-site SSO bridge.
@@ -103,6 +102,135 @@ var PlatformAuthClient = class {
 	}
 };
 //#endregion
+//#region src/platform/integrations.ts
+/** Thrown when a `PlatformHubClient` request returns a non-success status. */
+var PlatformHubError = class extends Error {
+	status;
+	code;
+	body;
+	constructor(message, status, code, body) {
+		super(message);
+		this.status = status;
+		this.code = code;
+		this.body = body;
+		this.name = "PlatformHubError";
+	}
+};
+/** HTTP client for the Tangle Platform Hub API: provider catalog, connection flow, and status. */
+var PlatformHubClient = class {
+	baseUrl;
+	bearer;
+	fetchImpl;
+	constructor(options) {
+		if (!options.baseUrl) throw new Error("PlatformHubClient: baseUrl is required");
+		if (!options.bearer) throw new Error("PlatformHubClient: bearer is required");
+		this.baseUrl = options.baseUrl.replace(/\/+$/, "");
+		this.bearer = options.bearer;
+		this.fetchImpl = options.fetchImpl ?? ((url, init) => fetch(url, init));
+	}
+	/** GET /v1/hub/providers — the connectable provider catalog. */
+	catalog() {
+		return this.request("GET", "/v1/hub/providers");
+	}
+	/** GET /v1/hub/connections — the calling user's live connections. */
+	async listConnections() {
+		return (await this.request("GET", "/v1/hub/connections")).connections;
+	}
+	/** DELETE /v1/hub/connections/:connectionId — revoke + disable a connection. */
+	revokeConnection(connectionId) {
+		return this.request("DELETE", `/v1/hub/connections/${encodeURIComponent(connectionId)}`);
+	}
+	/**
+	* POST /v1/hub/connections/:provider/start — begin OAuth/grant. The provider
+	* is taken from the URL; the body carries `returnUrl` (+ `cli`). The platform's
+	* two start branches name the URL field differently (github → `authorizationUrl`,
+	* substrate → `redirectUrl`); this normalizes to `authorizationUrl`.
+	*/
+	async startAuth(input) {
+		const body = { returnUrl: input.returnUrl };
+		if (input.cli !== void 0) body.cli = input.cli;
+		const data = await this.request("POST", `/v1/hub/connections/${encodeURIComponent(input.providerId)}/start`, body);
+		const authorizationUrl = data.authorizationUrl ?? data.redirectUrl;
+		if (!authorizationUrl) throw new PlatformHubError("Platform hub start response missing an authorization URL", 502, "HUB_INVALID_START_RESPONSE", data);
+		return {
+			authorizationUrl,
+			state: data.state,
+			expiresAt: data.expiresAt,
+			scopes: data.scopes
+		};
+	}
+	/**
+	* Last-known health for every connection. The platform has no global
+	* healthcheck listing — health rides on each connection row — so this derives
+	* the list from `listConnections()` (one request, no extra round-trips).
+	*/
+	async listHealthchecks() {
+		return (await this.listConnections()).map((c) => ({
+			connectionId: c.id,
+			providerId: c.providerId,
+			status: c.health,
+			checkedAt: c.updatedAt
+		}));
+	}
+	/**
+	* POST /v1/hub/connections/:connectionId/health — trigger a fresh health
+	* probe for one connection and return its updated state.
+	*/
+	checkConnectionHealth(connectionId) {
+		return this.request("POST", `/v1/hub/connections/${encodeURIComponent(connectionId)}/health`);
+	}
+	/**
+	* Trigger a fresh health probe across all of the user's connections. The
+	* platform exposes health per-connection only, so this fans out over
+	* `listConnections()`. `scheduled` is the number of probes dispatched.
+	*/
+	async runHealthchecks() {
+		const connections = await this.listConnections();
+		await Promise.allSettled(connections.map((c) => this.checkConnectionHealth(c.id)));
+		return { scheduled: connections.length };
+	}
+	/** GET /v1/hub/status — principal + aggregate connection counts. */
+	status() {
+		return this.request("GET", "/v1/hub/status");
+	}
+	/**
+	* POST /v1/hub/tokens — mint a short-lived, action-scoped capability token a
+	* sandbox can use to invoke one hub action on the user's behalf without
+	* seeing the underlying provider credential.
+	*/
+	mintToken(input) {
+		return this.request("POST", "/v1/hub/tokens", input);
+	}
+	/** POST /v1/hub/exec — execute a hub action and return its result. */
+	async exec(input) {
+		return (await this.request("POST", "/v1/hub/exec", input)).result;
+	}
+	async request(method, path, body) {
+		const headers = {
+			authorization: `Bearer ${this.bearer}`,
+			accept: "application/json"
+		};
+		if (body !== void 0) headers["content-type"] = "application/json";
+		const res = await this.fetchImpl(`${this.baseUrl}${path}`, {
+			method,
+			headers,
+			body: body !== void 0 ? JSON.stringify(body) : void 0
+		});
+		const text = await res.text();
+		let parsed = null;
+		if (text) try {
+			parsed = JSON.parse(text);
+		} catch {}
+		if (!res.ok || parsed && parsed.success === false) {
+			const code = parsed?.error && typeof parsed.error === "object" ? parsed.error.code : void 0;
+			throw new PlatformHubError(parsed?.error && typeof parsed.error === "object" && parsed.error.message || (typeof parsed?.error === "string" ? parsed.error : `Platform hub error (${res.status})`), res.status, code, parsed ?? text);
+		}
+		if (!parsed) throw new PlatformHubError(`Platform hub returned non-JSON success (${res.status})`, res.status, void 0, text);
+		if (parsed.data === void 0) throw new PlatformHubError("Platform hub envelope missing `data`", res.status, void 0, parsed);
+		return parsed.data;
+	}
+};
+//#endregion
 //#region src/platform/oidc.ts
 /**
 * OpenID Connect client for the Tangle authorization server. Identity tokens