@theokit/sdk 4.63.0 → 4.63.2

package/dist/{chunk-AEOZTXVW.js.map → chunk-UNYXQ4M5.js.map}

@@ -1 +1 @@
-{"version":3,"sources":["../src/internal/structured-output-helpers.ts"],"names":[],"mappings":";;;;AAoBA,IAAI,OAAA;AAMG,SAAS,UAAA,GAAkC;AAChD,EAAA,IAAI,OAAA,KAAY,QAAW,OAAO,OAAA;AAClC,EAAA,MAAM,CAAA,GAAI,aAAA,CAAc,MAAA,CAAA,IAAA,CAAY,GAAG,CAAA;AACvC,EAAA,IAAI,GAAA;AACJ,EAAA,IAAI;AACF,IAAA,GAAA,GAAM,EAAE,KAAK,CAAA;AAAA,EACf,SAAS,KAAA,EAAO;AACd,IAAA,MAAM,IAAI,kBAAA;AAAA,MACR,qIAAA;AAAA,MAEA,EAAE,IAAA,EAAM,mBAAA,EAAqB,KAAA;AAAM,KACrC;AAAA,EACF;AACA,EAAA,OAAA,GAAW,IAAI,CAAA,IAAK,GAAA;AACpB,EAAA,OAAO,OAAA;AACT;AAQO,SAAS,cAAA,CACd,YACA,SAAA,EACY;AACZ,EAAA,OAAO;AAAA,IACL,IAAA,EAAM,QAAA;AAAA,IACN,WAAA,EAAa,kFAAA;AAAA,IACb,WAAA,EAAa,UAAA;AAAA,IACb,OAAA,EAAS,CAAC,KAAA,KAAU;AAClB,MAAA,MAAM,GAAA,GAAM,UAAU,KAAK,CAAA;AAG3B,MAAA,IAAI,OAAO,GAAA,KAAQ,QAAA,EAAU,OAAO,GAAA;AACpC,MAAA,IAAI,GAAA,YAAe,SAAS,OAAO,GAAA;AACnC,MAAA,OAAO,EAAA;AAAA,IACT;AAAA,GACF;AACF;AAMO,SAAS,2BAA2B,MAAA,EAS1B;AACf,EAAA,OAAO;AAAA,IACL,OAAO,MAAA,CAAO,KAAA;AAAA,IACd,OAAO,MAAA,CAAO,KAAA;AAAA,IACd,KAAA,EAAO,CAAC,MAAA,CAAO,UAAU,CAAA;AAAA,IACzB,YAAA,EACE,OAAO,YAAA,IACP,iGAAA;AAAA,IACF,GAAI,OAAO,MAAA,KAAW,MAAA,GAAY,EAAE,MAAA,EAAQ,MAAA,CAAO,MAAA,EAAO,GAAI,EAAC;AAAA,IAC/D,GAAI,OAAO,SAAA,KAAc,MAAA,GAAY,EAAE,SAAA,EAAW,MAAA,CAAO,SAAA,EAAU,GAAI;AAAC,GAC1E;AACF;AAMO,SAAS,aAAa,MAAA,EAAgE;AAC3F,EAAA,MAAM,IAAK,MAAA,CAAuE,KAAA;AAClF,EAAA,IAAI,MAAM,MAAA,EAAW,OAAO,EAAE,WAAA,EAAa,CAAA,EAAG,cAAc,CAAA,EAAE;AAC9D,EAAA,OAAO,EAAE,aAAa,CAAA,CAAE,WAAA,IAAe,GAAG,YAAA,EAAc,CAAA,CAAE,gBAAgB,CAAA,EAAE;AAC9E;AAMO,SAAS,gBAAgB,MAAA,EAAwB;AACtD,EAAA,OAAO,GAAG,MAAM;;AAAA,0FAAA,CAAA;AAClB;AAOO,SAAS,qBAAA,CACd,QACA,UAAA,EACA;AACA,EAAA,MAAM,IAAI,UAAA,EAAW;AAErB,EAAA,MAAM,aAAa,YAAA,CAAa,MAAA,EAAQ,EAAE,eAAA,EAAiB,OAAO,CAAA;AAClE,EAAA,OAAO;AAAA,IACL,CAAA;AAAA,IACA,UAAA;AAAA,IACA,YAAY,UAAA,IAAc,CAAA;AAAA,IAC1B,YAAA,EAAc,EAAE,WAAA,EAAa,CAAA,EAAG,cAAc,CAAA;AAAE,GAClD;AACF;AAQA,eAAsB,yBAAA,CACpB,OACA,OAAA,EACe;AACf,EAAA,MAAM,MAAM,OAAA,EAAQ;AACpB,EAAA,IAAI;AACF,IAAA,MAAM,OAAA,CAAQ,MAAM,OAAO,CAAA;AAAA,EAC7B,CAAA,CAAA,MAAQ;AAAA,EAER;AACF","file":"chunk-AEOZTXVW.js","sourcesContent":["import { createRequire } from \"node:module\";\nimport type { z as ZodNamespace, ZodType } from \"zod\";\nimport { ConfigurationError } from \"../errors.js\";\n\nimport type { AgentOptions, CustomTool, LocalOptions, ModelSelection } from \"../types/agent.js\";\nimport type { ProviderRoutingSettings } from \"../types/providers.js\";\nimport { toJsonSchema } from \"./zod/to-json-schema.js\";\n\n/**\n * Shared helpers for `Agent.generateObject` (ADR D33) and\n * `Agent.streamObject` (ADR D39). Both build a transient agent with a\n * single synthetic `output` tool whose handler captures the model's\n * structured response.\n *\n * Extracted from inline duplicates to keep jscpd quiet AND to keep the\n * two public APIs in lockstep.\n *\n * @internal\n */\n\nlet cachedZ: typeof ZodNamespace | undefined;\n\n/**\n * Load Zod via createRequire (it's an optional peer dep). Throws a typed\n * ConfigurationError if Zod isn't installed.\n */\nexport function requireZod(): typeof ZodNamespace {\n  if (cachedZ !== undefined) return cachedZ;\n  const r = createRequire(import.meta.url);\n  let mod: { z?: typeof ZodNamespace } & typeof ZodNamespace;\n  try {\n    mod = r(\"zod\") as typeof mod;\n  } catch (cause) {\n    throw new ConfigurationError(\n      \"Structured output requires the optional peer dependency `zod`. \" +\n        'Add `\"zod\": \"^3.25.0 || ^4.0.0\"` to your package.json and reinstall.',\n      { code: \"zod_not_installed\", cause },\n    );\n  }\n  cachedZ = (mod.z ?? mod) as typeof ZodNamespace;\n  return cachedZ;\n}\n\n/**\n * Build the synthetic `output` tool used by both `generateObject` and\n * `streamObject`. The handler captures the raw input on first call only\n * (EC-D10 / EC-6: parallel tool use in Claude 3.5+ may invoke `output`\n * twice; later calls are ignored).\n */\nexport function makeOutputTool(\n  jsonSchema: Record<string, unknown>,\n  onCapture: (input: unknown) => string | Promise<string> | undefined,\n): CustomTool {\n  return {\n    name: \"output\",\n    description: \"Call this tool with your final structured answer. Match the JSON schema exactly.\",\n    inputSchema: jsonSchema,\n    handler: (input) => {\n      const out = onCapture(input);\n      // Some callers throw a sentinel (generate-object) and never return.\n      // Others return a string (stream-object). Anything else → empty string.\n      if (typeof out === \"string\") return out;\n      if (out instanceof Promise) return out;\n      return \"\";\n    },\n  };\n}\n\n/**\n * Assemble the AgentOptions for the transient agent. Shared shape:\n * model + local + tools[output] + systemPrompt + apiKey.\n */\nexport function buildTransientAgentOptions(params: {\n  // SE8 — accepts the bare-string shorthand; forwarded to AgentOptions.model\n  // (normalized at Agent.create).\n  model: string | ModelSelection;\n  local: LocalOptions;\n  outputTool: CustomTool;\n  systemPrompt?: string;\n  apiKey?: string;\n  providers?: ProviderRoutingSettings;\n}): AgentOptions {\n  return {\n    model: params.model,\n    local: params.local,\n    tools: [params.outputTool],\n    systemPrompt:\n      params.systemPrompt ??\n      \"You produce structured output by calling the `output` tool exactly once. Match the JSON schema.\",\n    ...(params.apiKey !== undefined ? { apiKey: params.apiKey } : {}),\n    ...(params.providers !== undefined ? { providers: params.providers } : {}),\n  };\n}\n\n/**\n * Best-effort extraction of token usage from a run result. Local runtimes\n * may not expose it; default to zeros.\n */\nexport function extractUsage(result: unknown): { inputTokens: number; outputTokens: number } {\n  const u = (result as { usage?: { inputTokens?: number; outputTokens?: number } }).usage;\n  if (u === undefined) return { inputTokens: 0, outputTokens: 0 };\n  return { inputTokens: u.inputTokens ?? 0, outputTokens: u.outputTokens ?? 0 };\n}\n\n/**\n * Build the user-message prompt that instructs the model to call the\n * `output` tool with a schema-matched structured answer.\n */\nexport function buildToolPrompt(prompt: string): string {\n  return `${prompt}\\n\\nRespond by calling the \\`output\\` tool with the structured answer that matches the schema.`;\n}\n\n/**\n * One-shot setup shared by both `generateObject` and `streamObject`. Loads\n * Zod, computes the JSON schema, primes the captured-raw / usage / retry\n * state. Returns the values needed by the caller's loop.\n */\nexport function setupStructuredOutput<T extends ZodType>(\n  schema: T,\n  maxRetries: number | undefined,\n) {\n  const z = requireZod();\n  // Universal Zod 3+4 conversion (feature-detects native v4, falls back to lib on v3).\n  const jsonSchema = toJsonSchema(schema, { unrepresentable: \"any\" });\n  return {\n    z,\n    jsonSchema,\n    maxRetries: maxRetries ?? 1,\n    initialUsage: { inputTokens: 0, outputTokens: 0 },\n  };\n}\n\n/**\n * Cleanup the transient agent after generateObject/streamObject finish.\n * Disposes AND hard-deletes from the registry so the count stays stable.\n *\n * @internal\n */\nexport async function disposeAndDeleteTransient(\n  agent: { dispose: () => Promise<void>; agentId: string },\n  deletor: (agentId: string) => Promise<void>,\n): Promise<void> {\n  await agent.dispose();\n  try {\n    await deletor(agent.agentId);\n  } catch {\n    // Best-effort cleanup.\n  }\n}\n\nvoid (null as unknown as ZodType); // satisfies unused-import check\n"]}
+{"version":3,"sources":["../src/internal/structured-output-helpers.ts"],"names":[],"mappings":";;;;AAoBA,IAAI,OAAA;AAMG,SAAS,UAAA,GAAkC;AAChD,EAAA,IAAI,OAAA,KAAY,QAAW,OAAO,OAAA;AAClC,EAAA,MAAM,CAAA,GAAI,aAAA,CAAc,MAAA,CAAA,IAAA,CAAY,GAAG,CAAA;AACvC,EAAA,IAAI,GAAA;AACJ,EAAA,IAAI;AACF,IAAA,GAAA,GAAM,EAAE,KAAK,CAAA;AAAA,EACf,SAAS,KAAA,EAAO;AACd,IAAA,MAAM,IAAI,kBAAA;AAAA,MACR,qIAAA;AAAA,MAEA,EAAE,IAAA,EAAM,mBAAA,EAAqB,KAAA;AAAM,KACrC;AAAA,EACF;AACA,EAAA,OAAA,GAAW,IAAI,CAAA,IAAK,GAAA;AACpB,EAAA,OAAO,OAAA;AACT;AAQO,SAAS,cAAA,CACd,YACA,SAAA,EACY;AACZ,EAAA,OAAO;AAAA,IACL,IAAA,EAAM,QAAA;AAAA,IACN,WAAA,EAAa,kFAAA;AAAA,IACb,WAAA,EAAa,UAAA;AAAA,IACb,OAAA,EAAS,CAAC,KAAA,KAAU;AAClB,MAAA,MAAM,GAAA,GAAM,UAAU,KAAK,CAAA;AAG3B,MAAA,IAAI,OAAO,GAAA,KAAQ,QAAA,EAAU,OAAO,GAAA;AACpC,MAAA,IAAI,GAAA,YAAe,SAAS,OAAO,GAAA;AACnC,MAAA,OAAO,EAAA;AAAA,IACT;AAAA,GACF;AACF;AAMO,SAAS,2BAA2B,MAAA,EAS1B;AACf,EAAA,OAAO;AAAA,IACL,OAAO,MAAA,CAAO,KAAA;AAAA,IACd,OAAO,MAAA,CAAO,KAAA;AAAA,IACd,KAAA,EAAO,CAAC,MAAA,CAAO,UAAU,CAAA;AAAA,IACzB,YAAA,EACE,OAAO,YAAA,IACP,iGAAA;AAAA,IACF,GAAI,OAAO,MAAA,KAAW,MAAA,GAAY,EAAE,MAAA,EAAQ,MAAA,CAAO,MAAA,EAAO,GAAI,EAAC;AAAA,IAC/D,GAAI,OAAO,SAAA,KAAc,MAAA,GAAY,EAAE,SAAA,EAAW,MAAA,CAAO,SAAA,EAAU,GAAI;AAAC,GAC1E;AACF;AAMO,SAAS,aAAa,MAAA,EAAgE;AAC3F,EAAA,MAAM,IAAK,MAAA,CAAuE,KAAA;AAClF,EAAA,IAAI,MAAM,MAAA,EAAW,OAAO,EAAE,WAAA,EAAa,CAAA,EAAG,cAAc,CAAA,EAAE;AAC9D,EAAA,OAAO,EAAE,aAAa,CAAA,CAAE,WAAA,IAAe,GAAG,YAAA,EAAc,CAAA,CAAE,gBAAgB,CAAA,EAAE;AAC9E;AAMO,SAAS,gBAAgB,MAAA,EAAwB;AACtD,EAAA,OAAO,GAAG,MAAM;;AAAA,0FAAA,CAAA;AAClB;AAOO,SAAS,qBAAA,CACd,QACA,UAAA,EACA;AACA,EAAA,MAAM,IAAI,UAAA,EAAW;AAErB,EAAA,MAAM,aAAa,YAAA,CAAa,MAAA,EAAQ,EAAE,eAAA,EAAiB,OAAO,CAAA;AAClE,EAAA,OAAO;AAAA,IACL,CAAA;AAAA,IACA,UAAA;AAAA,IACA,YAAY,UAAA,IAAc,CAAA;AAAA,IAC1B,YAAA,EAAc,EAAE,WAAA,EAAa,CAAA,EAAG,cAAc,CAAA;AAAE,GAClD;AACF;AAQA,eAAsB,yBAAA,CACpB,OACA,OAAA,EACe;AACf,EAAA,MAAM,MAAM,OAAA,EAAQ;AACpB,EAAA,IAAI;AACF,IAAA,MAAM,OAAA,CAAQ,MAAM,OAAO,CAAA;AAAA,EAC7B,CAAA,CAAA,MAAQ;AAAA,EAER;AACF","file":"chunk-UNYXQ4M5.js","sourcesContent":["import { createRequire } from \"node:module\";\nimport type { z as ZodNamespace, ZodType } from \"zod\";\nimport { ConfigurationError } from \"../errors.js\";\n\nimport type { AgentOptions, CustomTool, LocalOptions, ModelSelection } from \"../types/agent.js\";\nimport type { ProviderRoutingSettings } from \"../types/providers.js\";\nimport { toJsonSchema } from \"./zod/to-json-schema.js\";\n\n/**\n * Shared helpers for `Agent.generateObject` (ADR D33) and\n * `Agent.streamObject` (ADR D39). Both build a transient agent with a\n * single synthetic `output` tool whose handler captures the model's\n * structured response.\n *\n * Extracted from inline duplicates to keep jscpd quiet AND to keep the\n * two public APIs in lockstep.\n *\n * @internal\n */\n\nlet cachedZ: typeof ZodNamespace | undefined;\n\n/**\n * Load Zod via createRequire (it's an optional peer dep). Throws a typed\n * ConfigurationError if Zod isn't installed.\n */\nexport function requireZod(): typeof ZodNamespace {\n  if (cachedZ !== undefined) return cachedZ;\n  const r = createRequire(import.meta.url);\n  let mod: { z?: typeof ZodNamespace } & typeof ZodNamespace;\n  try {\n    mod = r(\"zod\") as typeof mod;\n  } catch (cause) {\n    throw new ConfigurationError(\n      \"Structured output requires the optional peer dependency `zod`. \" +\n        'Add `\"zod\": \"^3.25.0 || ^4.0.0\"` to your package.json and reinstall.',\n      { code: \"zod_not_installed\", cause },\n    );\n  }\n  cachedZ = (mod.z ?? mod) as typeof ZodNamespace;\n  return cachedZ;\n}\n\n/**\n * Build the synthetic `output` tool used by both `generateObject` and\n * `streamObject`. The handler captures the raw input on first call only\n * (EC-D10 / EC-6: parallel tool use in Claude 3.5+ may invoke `output`\n * twice; later calls are ignored).\n */\nexport function makeOutputTool(\n  jsonSchema: Record<string, unknown>,\n  onCapture: (input: unknown) => string | Promise<string> | undefined,\n): CustomTool {\n  return {\n    name: \"output\",\n    description: \"Call this tool with your final structured answer. Match the JSON schema exactly.\",\n    inputSchema: jsonSchema,\n    handler: (input) => {\n      const out = onCapture(input);\n      // Some callers throw a sentinel (generate-object) and never return.\n      // Others return a string (stream-object). Anything else → empty string.\n      if (typeof out === \"string\") return out;\n      if (out instanceof Promise) return out;\n      return \"\";\n    },\n  };\n}\n\n/**\n * Assemble the AgentOptions for the transient agent. Shared shape:\n * model + local + tools[output] + systemPrompt + apiKey.\n */\nexport function buildTransientAgentOptions(params: {\n  // SE8 — accepts the bare-string shorthand; forwarded to AgentOptions.model\n  // (normalized at Agent.create).\n  model: string | ModelSelection;\n  local: LocalOptions;\n  outputTool: CustomTool;\n  systemPrompt?: string;\n  apiKey?: string;\n  providers?: ProviderRoutingSettings;\n}): AgentOptions {\n  return {\n    model: params.model,\n    local: params.local,\n    tools: [params.outputTool],\n    systemPrompt:\n      params.systemPrompt ??\n      \"You produce structured output by calling the `output` tool exactly once. Match the JSON schema.\",\n    ...(params.apiKey !== undefined ? { apiKey: params.apiKey } : {}),\n    ...(params.providers !== undefined ? { providers: params.providers } : {}),\n  };\n}\n\n/**\n * Best-effort extraction of token usage from a run result. Local runtimes\n * may not expose it; default to zeros.\n */\nexport function extractUsage(result: unknown): { inputTokens: number; outputTokens: number } {\n  const u = (result as { usage?: { inputTokens?: number; outputTokens?: number } }).usage;\n  if (u === undefined) return { inputTokens: 0, outputTokens: 0 };\n  return { inputTokens: u.inputTokens ?? 0, outputTokens: u.outputTokens ?? 0 };\n}\n\n/**\n * Build the user-message prompt that instructs the model to call the\n * `output` tool with a schema-matched structured answer.\n */\nexport function buildToolPrompt(prompt: string): string {\n  return `${prompt}\\n\\nRespond by calling the \\`output\\` tool with the structured answer that matches the schema.`;\n}\n\n/**\n * One-shot setup shared by both `generateObject` and `streamObject`. Loads\n * Zod, computes the JSON schema, primes the captured-raw / usage / retry\n * state. Returns the values needed by the caller's loop.\n */\nexport function setupStructuredOutput<T extends ZodType>(\n  schema: T,\n  maxRetries: number | undefined,\n) {\n  const z = requireZod();\n  // Universal Zod 3+4 conversion (feature-detects native v4, falls back to lib on v3).\n  const jsonSchema = toJsonSchema(schema, { unrepresentable: \"any\" });\n  return {\n    z,\n    jsonSchema,\n    maxRetries: maxRetries ?? 1,\n    initialUsage: { inputTokens: 0, outputTokens: 0 },\n  };\n}\n\n/**\n * Cleanup the transient agent after generateObject/streamObject finish.\n * Disposes AND hard-deletes from the registry so the count stays stable.\n *\n * @internal\n */\nexport async function disposeAndDeleteTransient(\n  agent: { dispose: () => Promise<void>; agentId: string },\n  deletor: (agentId: string) => Promise<void>,\n): Promise<void> {\n  await agent.dispose();\n  try {\n    await deletor(agent.agentId);\n  } catch {\n    // Best-effort cleanup.\n  }\n}\n\nvoid (null as unknown as ZodType); // satisfies unused-import check\n"]}

package/dist/{chunk-2BDH744Z.js → chunk-UTSRIDKZ.js}

@@ -1,4 +1,4 @@
-import { registerBuiltins, listProviders, getProviderProfile } from './chunk-Q4CMI2LP.js';
+import { registerBuiltins, listProviders, getProviderProfile } from './chunk-WLQNMXQE.js';
 
 // src/providers.ts
 function listProviders2() {
@@ -11,5 +11,5 @@ function getProviderProfile2(name) {
 }
 
 export { getProviderProfile2 as getProviderProfile, listProviders2 as listProviders };
-//# sourceMappingURL=chunk-2BDH744Z.js.map
-//# sourceMappingURL=chunk-2BDH744Z.js.map
+//# sourceMappingURL=chunk-UTSRIDKZ.js.map
+//# sourceMappingURL=chunk-UTSRIDKZ.js.map

package/dist/{chunk-2BDH744Z.js.map → chunk-UTSRIDKZ.js.map}

@@ -1 +1 @@
-{"version":3,"sources":["../src/providers.ts"],"names":["listProviders","getProviderProfile"],"mappings":";;;AA4BO,SAASA,cAAAA,GAA4C;AAC1D,EAAA,gBAAA,EAAiB;AACjB,EAAA,OAAO,aAAA,EAAa;AACtB;AAQO,SAASC,oBAAmB,IAAA,EAA2C;AAC5E,EAAA,gBAAA,EAAiB;AACjB,EAAA,OAAO,mBAAW,IAAI,CAAA;AACxB","file":"chunk-2BDH744Z.js","sourcesContent":["/**\n * The provider registry, as public API.\n *\n * It was `@internal`, which meant the SDK was the only thing that could answer \"which providers\n * exist, and what does each one need?\". `theokit` consequently kept a hand-written list of three —\n * against the 46 registered here — so an agent declaring `ollama/qwen2.5:3b` routed to whatever\n * key happened to be set instead of to Ollama (usetheokit/theokit#326).\n *\n * A second table that nothing forces to agree with the first is not a cache, it is a future bug.\n * These two functions exist so there is one table.\n *\n * Both ensure the builtins are registered before answering: registration is lazy (it happens when\n * an agent is created, a run is routed, or a provider is defined), so a caller asking early would\n * otherwise get an empty registry and reasonably conclude the SDK knows nothing.\n */\n\nimport { registerBuiltins } from \"./internal/providers/builtin/index.js\";\nimport {\n  getProviderProfile as getProfile,\n  listProviders as listProfiles,\n} from \"./internal/providers/registry.js\";\nimport type { ProviderProfile } from \"./internal/providers/types.js\";\n\n/**\n * Every registered provider — builtins, the JSON catalog, and anything a plugin registered.\n *\n * @public\n */\nexport function listProviders(): readonly ProviderProfile[] {\n  registerBuiltins();\n  return listProfiles();\n}\n\n/**\n * One provider by name or alias (`lm-studio` resolves to `lmstudio`), or `undefined` when nothing\n * has registered it.\n *\n * @public\n */\nexport function getProviderProfile(name: string): ProviderProfile | undefined {\n  registerBuiltins();\n  return getProfile(name);\n}\n"]}
+{"version":3,"sources":["../src/providers.ts"],"names":["listProviders","getProviderProfile"],"mappings":";;;AA4BO,SAASA,cAAAA,GAA4C;AAC1D,EAAA,gBAAA,EAAiB;AACjB,EAAA,OAAO,aAAA,EAAa;AACtB;AAQO,SAASC,oBAAmB,IAAA,EAA2C;AAC5E,EAAA,gBAAA,EAAiB;AACjB,EAAA,OAAO,mBAAW,IAAI,CAAA;AACxB","file":"chunk-UTSRIDKZ.js","sourcesContent":["/**\n * The provider registry, as public API.\n *\n * It was `@internal`, which meant the SDK was the only thing that could answer \"which providers\n * exist, and what does each one need?\". `theokit` consequently kept a hand-written list of three —\n * against the 46 registered here — so an agent declaring `ollama/qwen2.5:3b` routed to whatever\n * key happened to be set instead of to Ollama (usetheokit/theokit#326).\n *\n * A second table that nothing forces to agree with the first is not a cache, it is a future bug.\n * These two functions exist so there is one table.\n *\n * Both ensure the builtins are registered before answering: registration is lazy (it happens when\n * an agent is created, a run is routed, or a provider is defined), so a caller asking early would\n * otherwise get an empty registry and reasonably conclude the SDK knows nothing.\n */\n\nimport { registerBuiltins } from \"./internal/providers/builtin/index.js\";\nimport {\n  getProviderProfile as getProfile,\n  listProviders as listProfiles,\n} from \"./internal/providers/registry.js\";\nimport type { ProviderProfile } from \"./internal/providers/types.js\";\n\n/**\n * Every registered provider — builtins, the JSON catalog, and anything a plugin registered.\n *\n * @public\n */\nexport function listProviders(): readonly ProviderProfile[] {\n  registerBuiltins();\n  return listProfiles();\n}\n\n/**\n * One provider by name or alias (`lm-studio` resolves to `lmstudio`), or `undefined` when nothing\n * has registered it.\n *\n * @public\n */\nexport function getProviderProfile(name: string): ProviderProfile | undefined {\n  registerBuiltins();\n  return getProfile(name);\n}\n"]}

package/dist/{chunk-2ADR2GSO.cjs → chunk-UU36SHFY.cjs}

@@ -1,7 +1,7 @@
 'use strict';
 
 var chunkZF2LDKQQ_cjs = require('./chunk-ZF2LDKQQ.cjs');
-var chunkNUKRL3I6_cjs = require('./chunk-NUKRL3I6.cjs');
+var chunkEG4QM7ZJ_cjs = require('./chunk-EG4QM7ZJ.cjs');
 var fs = require('fs');
 var path = require('path');
 
@@ -32,7 +32,7 @@ async function getProperLockfile() {
     if (!validateLockModule(mod)) {
       if (!warnedStructural) {
         warnedStructural = true;
-        chunkNUKRL3I6_cjs.diag(
+        chunkEG4QM7ZJ_cjs.diag(
           "[theokit-sdk] proper-lockfile: imported module does NOT expose the expected `lock`/`unlock` API surface. This may indicate a supply-chain compromise or an incompatible major version. Falling back to in-process mutex (no cross-process safety). Reinstall with: pnpm add proper-lockfile@^11\n"
         );
       }
@@ -56,7 +56,7 @@ async function withFileLock(path, fn, options) {
   if (lib === null) {
     if (!warnedMissing && !warnedStructural) {
       warnedMissing = true;
-      chunkNUKRL3I6_cjs.diag(describeLockLoadFailure(loadFailure));
+      chunkEG4QM7ZJ_cjs.diag(describeLockLoadFailure(loadFailure));
     }
     return chunkZF2LDKQQ_cjs.withCwdMutex(`file-lock:${path}`, fn);
   }
@@ -181,5 +181,5 @@ exports.appendJsonl = appendJsonl;
 exports.loadJsonl = loadJsonl;
 exports.readJsonlIds = readJsonlIds;
 exports.withFileLock = withFileLock;
-//# sourceMappingURL=chunk-2ADR2GSO.cjs.map
-//# sourceMappingURL=chunk-2ADR2GSO.cjs.map
+//# sourceMappingURL=chunk-UU36SHFY.cjs.map
+//# sourceMappingURL=chunk-UU36SHFY.cjs.map

package/dist/{chunk-2ADR2GSO.cjs.map → chunk-UU36SHFY.cjs.map}

@@ -1 +1 @@
-{"version":3,"sources":["../src/internal/persistence/file-lock.ts","../src/internal/persistence/jsonl.ts"],"names":["diag","withCwdMutex","readFileSync","path","mkdirSync","dirname","openSync","writeSync","closeSync","fstatSync","readSync"],"mappings":"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","file":"chunk-2ADR2GSO.cjs","sourcesContent":["/**\n * Cross-process file lock helper (ADR D61).\n *\n * Uses `proper-lockfile` (optional peer dep) for cross-process locks. When\n * the peer dep is absent, falls back to `withCwdMutex` (in-process only)\n * with a one-shot stderr warning.\n *\n * EC-1 fix: uses a companion `<path>.lock` file with `realpath: false` so\n * `withFileLock` works even when the target `path` does not exist yet.\n * Without this, fresh installs that lock-then-create would crash with ENOENT.\n *\n * @internal\n */\n\nimport { diag } from \"../diagnostics.js\";\nimport { withCwdMutex } from \"./cwd-mutex.js\";\n\ninterface ProperLockfileModule {\n  lock: (file: string, options: ProperLockfileOptions) => Promise<() => Promise<void>>;\n}\n\ninterface ProperLockfileOptions {\n  lockfilePath?: string;\n  realpath?: boolean;\n  stale?: number;\n  retries?: {\n    retries: number;\n    factor?: number;\n    minTimeout?: number;\n    maxTimeout?: number;\n  };\n}\n\nlet cached: ProperLockfileModule | null | undefined;\nlet warnedMissing = false;\nlet warnedStructural = false;\n/** Why the import failed, kept so the warning can report the observation instead of a guess (#174). */\nlet loadFailure: unknown;\n\n/** Node reports a missing module as `ERR_MODULE_NOT_FOUND` (ESM loader) or `MODULE_NOT_FOUND` (CJS). */\nfunction isModuleAbsent(err: unknown): boolean {\n  const code = (err as { code?: unknown } | null | undefined)?.code;\n  return code === \"ERR_MODULE_NOT_FOUND\" || code === \"MODULE_NOT_FOUND\";\n}\n\n/**\n * #174 — build the fallback warning from what actually happened.\n *\n * This used to always read \"proper-lockfile not installed\", because the import was wrapped in a\n * bare `catch` that discarded the error (Unbreakable Rule 8: a swallowed error is the dangerous\n * kind). A consumer whose package WAS installed, declared and resolvable spent a debugging session\n * re-verifying the install, because the message named a cause the code had never checked.\n *\n * Absence is now the only case that claims absence. Every other failure — a broken install, an\n * interop problem, a bundler that rewrote the specifier — reports its own code and message, which\n * is what points at the real cause.\n *\n * @internal\n */\nfunction describeLockLoadFailure(err: unknown): string {\n  const consequence =\n    \"cross-process file lock unavailable — concurrent processes over the same file are NOT serialized.\";\n  if (isModuleAbsent(err)) {\n    return `[theokit-sdk] proper-lockfile not installed; ${consequence} Install with: pnpm add proper-lockfile\\n`;\n  }\n  const code = (err as { code?: unknown } | null | undefined)?.code;\n  const detail = err instanceof Error ? err.message : String(err);\n  return (\n    `[theokit-sdk] proper-lockfile could not be loaded${code !== undefined ? ` (${String(code)})` : \"\"}: ` +\n    `${detail}. ${consequence} The package resolves for the SDK but failed to load — check bundling ` +\n    \"and module-format interop before re-checking the install.\\n\"\n  );\n}\n\n/** Test seam for the message builder — NOT in the public barrel. @internal */\nexport function __TESTING__describeLockLoadFailure(err: unknown): string {\n  return describeLockLoadFailure(err);\n}\n\nasync function getProperLockfile(): Promise<ProperLockfileModule | null> {\n  if (cached !== undefined) return cached;\n  try {\n    const mod = await import(\"proper-lockfile\");\n    // T5.9 — supply-chain hardening: validate the imported module\n    // exposes the API surface we depend on BEFORE caching it. A\n    // tampered or incompatible version that lacks `lock`/`unlock`\n    // functions gets treated as \"not installed\" with an advisory\n    // warning — never silently used.\n    if (!validateLockModule(mod)) {\n      if (!warnedStructural) {\n        warnedStructural = true;\n        diag(\n          \"[theokit-sdk] proper-lockfile: imported module does NOT expose \" +\n            \"the expected `lock`/`unlock` API surface. This may indicate a \" +\n            \"supply-chain compromise or an incompatible major version. \" +\n            \"Falling back to in-process mutex (no cross-process safety). \" +\n            \"Reinstall with: pnpm add proper-lockfile@^11\\n\",\n        );\n      }\n      cached = null;\n      return cached;\n    }\n    cached = mod as ProperLockfileModule;\n  } catch (err) {\n    // #174 — keep WHY. Discarding it here is what made the fallback warning assert a cause it had\n    // never observed, and sent a consumer to re-check an install that was already correct.\n    loadFailure = err;\n    cached = null;\n  }\n  return cached;\n}\n\n/**\n * T5.9 — Structural validation of the dynamically-imported\n * `proper-lockfile` module. Verifies the API surface we depend on\n * (`lock` and `unlock` as functions) is present. Pure function —\n * never throws, never mutates, never performs I/O.\n *\n * Exported via `__TESTING__validateLockModule` seam so unit tests\n * can drive the check without spinning up the dynamic import.\n *\n * @internal\n */\nfunction validateLockModule(mod: unknown): boolean {\n  if (mod === null || mod === undefined || typeof mod !== \"object\") return false;\n  const m = mod as Record<string, unknown>;\n  return typeof m.lock === \"function\" && typeof m.unlock === \"function\";\n}\n\n/**\n * T5.9 — Test seam: expose the structural validator for unit tests.\n * NOT included in the public barrel.\n *\n * @internal\n */\nexport function __TESTING__validateLockModule(mod: unknown): boolean {\n  return validateLockModule(mod);\n}\n\n/**\n * T5.9 — Test seam: reset the module cache + warning flags between\n * tests so each test starts fresh. NOT included in the public barrel.\n *\n * @internal\n */\nexport function __TESTING__resetFileLockCache(): void {\n  cached = undefined;\n  warnedMissing = false;\n  warnedStructural = false;\n  loadFailure = undefined;\n}\n\n/**\n * Retry and staleness tuning for `withFileLock`.\n *\n * Every field is optional and the defaults are applied per call, so `undefined` means the default\n * rather than \"no limit\". They are handed to `proper-lockfile` and have NO effect on the fallback\n * path: when that package is absent, `withFileLock` degrades to the in-process mutex, which\n * queues indefinitely and never goes stale.\n *\n * `stale` (default 30000 ms) is how old a lock file must be before it is treated as abandoned by a\n * dead process and broken. Setting it below the longest a legitimate holder can run is what turns\n * a slow operation into two concurrent ones.\n *\n * `retries` (default 5) is the number of acquisition attempts AFTER the first, and `retryFactor`\n * (default 1.5) the backoff multiplier between them. The per-attempt wait is clamped to\n * 100–5000 ms, which the caller cannot change. Exhausting the retries rejects — it does not fall\n * through to running `fn` unlocked.\n *\n * @public — re-exported from the semver-protected `@theokit/sdk/persistence` barrel, and (for\n * back-compat) from the semver-exempt `@theokit/sdk/internal/persistence` alias.\n */\nexport interface FileLockOptions {\n  /** Stale lock timeout in ms. Default 30_000 (30s). */\n  stale?: number;\n  /** Max retries on busy lock. Default 5. */\n  retries?: number;\n  /** Backoff factor between retries. Default 1.5. */\n  retryFactor?: number;\n}\n\n/**\n * Run `fn` while holding an OS-level cross-process lock on `path`.\n *\n * If `proper-lockfile` is installed, uses it with a companion `<path>.lock`\n * file (`realpath: false`, so target file does NOT need to exist yet).\n * Otherwise falls back to in-process `withCwdMutex` and prints a one-shot\n * stderr warning telling the user to install `proper-lockfile` for\n * cross-process safety.\n *\n * The lock is released even when `fn` throws.\n *\n */\nexport async function withFileLock<T>(\n  path: string,\n  fn: () => Promise<T>,\n  options?: FileLockOptions,\n): Promise<T> {\n  const lib = await getProperLockfile();\n\n  if (lib === null) {\n    // #174 — stay silent when the structural check already explained itself. Emitting \"not\n    // installed\" on top of \"does not expose lock/unlock\" would be two contradictory diagnoses of\n    // one failure, and the reader has no way to tell which is true.\n    if (!warnedMissing && !warnedStructural) {\n      warnedMissing = true;\n      diag(describeLockLoadFailure(loadFailure));\n    }\n    return withCwdMutex(`file-lock:${path}`, fn);\n  }\n\n  // proper-lockfile errors immediately on same-process concurrent acquire\n  // (\"Lock file is already being held\"). Wrap with cwd-mutex first so\n  // in-process callers queue and only ONE thread at a time enters the\n  // cross-process acquire path. Combined: full in-process + cross-process\n  // serialization.\n  return withCwdMutex(`file-lock:${path}`, async () => {\n    const release = await lib.lock(path, {\n      // EC-1: companion lockfile, target path may not exist yet.\n      lockfilePath: `${path}.lock`,\n      realpath: false,\n      stale: options?.stale ?? 30_000,\n      retries: {\n        retries: options?.retries ?? 5,\n        factor: options?.retryFactor ?? 1.5,\n        minTimeout: 100,\n        maxTimeout: 5_000,\n      },\n    });\n\n    try {\n      return await fn();\n    } finally {\n      await release();\n    }\n  });\n}\n\n/**\n * Test helper — resets the cached proper-lockfile module + warning flag.\n * Allows tests to simulate \"module absent\" by clearing cache then\n * monkey-patching the dynamic import resolution.\n *\n * @internal\n */\nexport function _resetFileLockCacheForTesting(): void {\n  cached = undefined;\n  warnedMissing = false;\n}\n","/**\n * Durable JSONL primitives shared by the eval harness (M6).\n *\n * - `loadJsonl` — generic dataset reader (split/trim/skip-blank/parse) with a\n *   line-numbered {@link JsonlParseError}. The dataset SCHEMA is the caller's\n *   concern via `map` (M6 ADR D3) — this module owns only the parse.\n * - `appendJsonl` / `readJsonlIds` — crash-durable, resumable batch persistence\n *   (M6 ADR D1): each record is appended as one whole `\\n`-terminated line the\n *   instant it is produced, and a re-run resumes by skipping already-keyed rows.\n *\n * reference: knowledge-base/references/theocode-eval/lib/swebench-dataset.ts:82\n * (parseJsonl + line-N error) and swebench-batch.ts:113,205 (resume + per-line\n * flush).\n *\n * @internal\n */\nimport {\n  closeSync,\n  fstatSync,\n  mkdirSync,\n  openSync,\n  readFileSync,\n  readSync,\n  writeSync,\n} from \"node:fs\";\nimport { dirname } from \"node:path\";\n\n/** Raised when a JSONL line is not valid JSON or is not a JSON object. Carries the 1-based line number. */\nexport class JsonlParseError extends Error {\n  constructor(\n    message: string,\n    readonly line: number,\n  ) {\n    super(message);\n    this.name = \"JsonlParseError\";\n  }\n}\n\nfunction isPlainObject(value: unknown): value is Record<string, unknown> {\n  return typeof value === \"object\" && value !== null && !Array.isArray(value);\n}\n\n/** Parse a single trimmed line to a plain object, or `undefined` if blank / invalid / non-object. */\nfunction tryParseObjectLine(line: string): Record<string, unknown> | undefined {\n  if (line.length === 0) return undefined;\n  let parsed: unknown;\n  try {\n    parsed = JSON.parse(line);\n  } catch {\n    return undefined;\n  }\n  return isPlainObject(parsed) ? parsed : undefined;\n}\n\n/**\n * Parse a JSONL file into rows. Blank lines are skipped. A malformed or\n * non-object line throws {@link JsonlParseError} naming the 1-based line. When\n * `map` is provided, each raw object is mapped to the typed row (the SWE-bench\n * schema lives in the caller's `map`, per M6 ADR D3).\n */\nexport function loadJsonl<T = Record<string, unknown>>(\n  path: string,\n  opts: {\n    map?: (raw: Record<string, unknown>, lineNumber: number) => T;\n    /**\n     * M81 — tolerate a truncated LAST line (a crash artifact: the process died mid-write).\n     *\n     * Opt-in on purpose. As a default it would also swallow corruption in the MIDDLE of the file,\n     * turning loud data loss into silent data loss — the wrong trade for a session store.\n     */\n    tolerateTrailingPartialLine?: boolean;\n  } = {},\n): T[] {\n  const lines = readFileSync(path, \"utf8\").split(\"\\n\");\n  const out: T[] = [];\n  for (let i = 0; i < lines.length; i += 1) {\n    const lineNumber = i + 1;\n    const line = (lines[i] ?? \"\").trim();\n    if (line.length === 0) continue;\n    // M81 — `undefined` = a tolerated invalid line (the last one, truncated by a crash). Any other\n    // invalid line has already thrown inside `parseLine`.\n    const parsed = parseLine(\n      line,\n      lineNumber,\n      opts.tolerateTrailingPartialLine === true && lineNumber === lines.length,\n    );\n    if (parsed === undefined) break;\n    out.push(opts.map ? opts.map(parsed, lineNumber) : (parsed as unknown as T));\n  }\n  return out;\n}\n\n/**\n * Parses ONE line, returning `undefined` when it is a tolerated truncated last line.\n *\n * Extracted because `loadJsonl` went over the cognitive-complexity ceiling once it gained the\n * tolerance — and because parsing a line and iterating a file are two responsibilities that were\n * only together out of habit.\n */\nfunction parseLine(\n  line: string,\n  lineNumber: number,\n  tolerate: boolean,\n): Record<string, unknown> | undefined {\n  let parsed: unknown;\n  try {\n    parsed = JSON.parse(line);\n  } catch {\n    if (tolerate) return undefined;\n    throw new JsonlParseError(`line ${lineNumber}: invalid JSON`, lineNumber);\n  }\n  if (!isPlainObject(parsed)) {\n    throw new JsonlParseError(`line ${lineNumber}: not a JSON object`, lineNumber);\n  }\n  return parsed;\n}\n\n/**\n * Append one record as a whole `\\n`-terminated JSON line. Creates the parent dir\n * if missing. `appendFileSync` is synchronous, so within a single Node process\n * the event loop serializes writes and each call writes its line atomically —\n * interleave-safe for the bounded-concurrency batch runner.\n *\n * reference: swebench-batch.ts:192 (mkdir-before-append), :205 (per-line flush).\n */\nexport function appendJsonl(path: string, record: unknown): void {\n  // T2.4 — `0o700` for the same reason the file below is `0o600`, and it is the half M93 missed. A\n  // private file inside a group-writable directory can be replaced wholesale, and the replacement's\n  // mode is whatever the writer chose. Under `umask 002` this directory was born `0775`.\n  //\n  // The directory sits under `~/.theokit`, shared with the credential and trust stores, and the\n  // framework already wrote the diagnosis while fixing a sibling (`@theokit/agents\n  // config/trust-store.ts:157-161`): the mode argument is a no-op on a directory that already\n  // exists, \"and this one is shared with the SDK's transcript root — whoever creates it first sets\n  // the permissions\". Whoever creates it first is usually THIS function, because a session writes a\n  // transcript before it ever touches a credential. So `assertSecureModes` was not wrong to demand a\n  // private directory; this path was wrong to produce one that fails it, depending on run order.\n  //\n  // Creation-time only, deliberately: repairing a pre-existing directory means `stat` + `chmod` on\n  // every append, and this is the hot path of every session. The pre-existing case is what\n  // `assertSecureModes` is for.\n  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });\n  const prefix = needsLineBreakBefore(path) ? \"\\n\" : \"\";\n  // M93 (adversarial review, H1) — `0o600`. `appendFileSync` takes no `mode`, so the permission came\n  // from the umask: under `umask 022` the transcript was born `0664`, world-readable. The previous\n  // path (`replaceFileAtomic`) pinned `0o600` on purpose — \"holds the FULL in-flight content\n  // (credential snapshots, OAuth tokens)\" (`atomic-write.ts:107`) — and switching to append lost\n  // that silently. The same class had already been caught in the consumer (`atomic-sync.ts`, M88\n  // HIGH-1).\n  //\n  // `mode` only applies on CREATION; a pre-existing file keeps whatever permission it already has.\n  const fd = openSync(path, \"a\", 0o600);\n  try {\n    writeSync(fd, `${prefix}${JSON.stringify(record)}\\n`);\n  } finally {\n    closeSync(fd);\n  }\n}\n\n/**\n * Does the file end without a `\\n`? Then the last line is truncated — a crash mid-append.\n *\n * Without this check the next append **glues** itself onto the middle of the broken line, producing\n * an invalid line the reader discards: the NEW record disappears along with the partial one. The\n * previous path (read-modify-write) self-healed from this because it rewrote the whole file.\n * Measured in M93's adversarial review (H2): after an append over a truncated file, the\n * just-written record was no longer readable.\n *\n * Reads **one byte**, not the file.\n */\nfunction needsLineBreakBefore(path: string): boolean {\n  let fd: number;\n  try {\n    fd = openSync(path, \"r\");\n  } catch {\n    return false; // the file does not exist yet: nothing to splice onto\n  }\n  try {\n    const size = fstatSync(fd).size;\n    if (size === 0) return false;\n    const buf = Buffer.alloc(1);\n    readSync(fd, buf, 0, 1, size - 1);\n    return buf[0] !== 0x0a;\n  } finally {\n    closeSync(fd);\n  }\n}\n\n/**\n * Read the set of keys from an existing JSONL file for which `keyFn(parsed)`\n * returns a non-empty string. Used to resume a crashed batch by skipping rows\n * already persisted with a successful result. A trailing partial line from an\n * interrupted append is tolerated (skipped, not thrown), and a missing file\n * yields an empty set.\n *\n * reference: swebench-batch.ts:113 (readDoneIds), :129 (success-only),\n * :131 (tolerate partial line).\n */\nexport function readJsonlIds(\n  path: string,\n  keyFn: (parsed: Record<string, unknown>) => string | undefined,\n): Set<string> {\n  const done = new Set<string>();\n  let text: string;\n  try {\n    text = readFileSync(path, \"utf8\");\n  } catch {\n    return done; // no file yet → nothing done\n  }\n  for (const rawLine of text.split(\"\\n\")) {\n    // A trailing partial line from an interrupted run parses to undefined → skipped.\n    const parsed = tryParseObjectLine(rawLine.trim());\n    if (parsed === undefined) continue;\n    const key = keyFn(parsed);\n    if (typeof key === \"string\" && key.length > 0) done.add(key);\n  }\n  return done;\n}\n"]}
+{"version":3,"sources":["../src/internal/persistence/file-lock.ts","../src/internal/persistence/jsonl.ts"],"names":["diag","withCwdMutex","readFileSync","path","mkdirSync","dirname","openSync","writeSync","closeSync","fstatSync","readSync"],"mappings":"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","file":"chunk-UU36SHFY.cjs","sourcesContent":["/**\n * Cross-process file lock helper (ADR D61).\n *\n * Uses `proper-lockfile` (optional peer dep) for cross-process locks. When\n * the peer dep is absent, falls back to `withCwdMutex` (in-process only)\n * with a one-shot stderr warning.\n *\n * EC-1 fix: uses a companion `<path>.lock` file with `realpath: false` so\n * `withFileLock` works even when the target `path` does not exist yet.\n * Without this, fresh installs that lock-then-create would crash with ENOENT.\n *\n * @internal\n */\n\nimport { diag } from \"../diagnostics.js\";\nimport { withCwdMutex } from \"./cwd-mutex.js\";\n\ninterface ProperLockfileModule {\n  lock: (file: string, options: ProperLockfileOptions) => Promise<() => Promise<void>>;\n}\n\ninterface ProperLockfileOptions {\n  lockfilePath?: string;\n  realpath?: boolean;\n  stale?: number;\n  retries?: {\n    retries: number;\n    factor?: number;\n    minTimeout?: number;\n    maxTimeout?: number;\n  };\n}\n\nlet cached: ProperLockfileModule | null | undefined;\nlet warnedMissing = false;\nlet warnedStructural = false;\n/** Why the import failed, kept so the warning can report the observation instead of a guess (#174). */\nlet loadFailure: unknown;\n\n/** Node reports a missing module as `ERR_MODULE_NOT_FOUND` (ESM loader) or `MODULE_NOT_FOUND` (CJS). */\nfunction isModuleAbsent(err: unknown): boolean {\n  const code = (err as { code?: unknown } | null | undefined)?.code;\n  return code === \"ERR_MODULE_NOT_FOUND\" || code === \"MODULE_NOT_FOUND\";\n}\n\n/**\n * #174 — build the fallback warning from what actually happened.\n *\n * This used to always read \"proper-lockfile not installed\", because the import was wrapped in a\n * bare `catch` that discarded the error (Unbreakable Rule 8: a swallowed error is the dangerous\n * kind). A consumer whose package WAS installed, declared and resolvable spent a debugging session\n * re-verifying the install, because the message named a cause the code had never checked.\n *\n * Absence is now the only case that claims absence. Every other failure — a broken install, an\n * interop problem, a bundler that rewrote the specifier — reports its own code and message, which\n * is what points at the real cause.\n *\n * @internal\n */\nfunction describeLockLoadFailure(err: unknown): string {\n  const consequence =\n    \"cross-process file lock unavailable — concurrent processes over the same file are NOT serialized.\";\n  if (isModuleAbsent(err)) {\n    return `[theokit-sdk] proper-lockfile not installed; ${consequence} Install with: pnpm add proper-lockfile\\n`;\n  }\n  const code = (err as { code?: unknown } | null | undefined)?.code;\n  const detail = err instanceof Error ? err.message : String(err);\n  return (\n    `[theokit-sdk] proper-lockfile could not be loaded${code !== undefined ? ` (${String(code)})` : \"\"}: ` +\n    `${detail}. ${consequence} The package resolves for the SDK but failed to load — check bundling ` +\n    \"and module-format interop before re-checking the install.\\n\"\n  );\n}\n\n/** Test seam for the message builder — NOT in the public barrel. @internal */\nexport function __TESTING__describeLockLoadFailure(err: unknown): string {\n  return describeLockLoadFailure(err);\n}\n\nasync function getProperLockfile(): Promise<ProperLockfileModule | null> {\n  if (cached !== undefined) return cached;\n  try {\n    const mod = await import(\"proper-lockfile\");\n    // T5.9 — supply-chain hardening: validate the imported module\n    // exposes the API surface we depend on BEFORE caching it. A\n    // tampered or incompatible version that lacks `lock`/`unlock`\n    // functions gets treated as \"not installed\" with an advisory\n    // warning — never silently used.\n    if (!validateLockModule(mod)) {\n      if (!warnedStructural) {\n        warnedStructural = true;\n        diag(\n          \"[theokit-sdk] proper-lockfile: imported module does NOT expose \" +\n            \"the expected `lock`/`unlock` API surface. This may indicate a \" +\n            \"supply-chain compromise or an incompatible major version. \" +\n            \"Falling back to in-process mutex (no cross-process safety). \" +\n            \"Reinstall with: pnpm add proper-lockfile@^11\\n\",\n        );\n      }\n      cached = null;\n      return cached;\n    }\n    cached = mod as ProperLockfileModule;\n  } catch (err) {\n    // #174 — keep WHY. Discarding it here is what made the fallback warning assert a cause it had\n    // never observed, and sent a consumer to re-check an install that was already correct.\n    loadFailure = err;\n    cached = null;\n  }\n  return cached;\n}\n\n/**\n * T5.9 — Structural validation of the dynamically-imported\n * `proper-lockfile` module. Verifies the API surface we depend on\n * (`lock` and `unlock` as functions) is present. Pure function —\n * never throws, never mutates, never performs I/O.\n *\n * Exported via `__TESTING__validateLockModule` seam so unit tests\n * can drive the check without spinning up the dynamic import.\n *\n * @internal\n */\nfunction validateLockModule(mod: unknown): boolean {\n  if (mod === null || mod === undefined || typeof mod !== \"object\") return false;\n  const m = mod as Record<string, unknown>;\n  return typeof m.lock === \"function\" && typeof m.unlock === \"function\";\n}\n\n/**\n * T5.9 — Test seam: expose the structural validator for unit tests.\n * NOT included in the public barrel.\n *\n * @internal\n */\nexport function __TESTING__validateLockModule(mod: unknown): boolean {\n  return validateLockModule(mod);\n}\n\n/**\n * T5.9 — Test seam: reset the module cache + warning flags between\n * tests so each test starts fresh. NOT included in the public barrel.\n *\n * @internal\n */\nexport function __TESTING__resetFileLockCache(): void {\n  cached = undefined;\n  warnedMissing = false;\n  warnedStructural = false;\n  loadFailure = undefined;\n}\n\n/**\n * Retry and staleness tuning for `withFileLock`.\n *\n * Every field is optional and the defaults are applied per call, so `undefined` means the default\n * rather than \"no limit\". They are handed to `proper-lockfile` and have NO effect on the fallback\n * path: when that package is absent, `withFileLock` degrades to the in-process mutex, which\n * queues indefinitely and never goes stale.\n *\n * `stale` (default 30000 ms) is how old a lock file must be before it is treated as abandoned by a\n * dead process and broken. Setting it below the longest a legitimate holder can run is what turns\n * a slow operation into two concurrent ones.\n *\n * `retries` (default 5) is the number of acquisition attempts AFTER the first, and `retryFactor`\n * (default 1.5) the backoff multiplier between them. The per-attempt wait is clamped to\n * 100–5000 ms, which the caller cannot change. Exhausting the retries rejects — it does not fall\n * through to running `fn` unlocked.\n *\n * @public — re-exported from the semver-protected `@theokit/sdk/persistence` barrel, and (for\n * back-compat) from the semver-exempt `@theokit/sdk/internal/persistence` alias.\n */\nexport interface FileLockOptions {\n  /** Stale lock timeout in ms. Default 30_000 (30s). */\n  stale?: number;\n  /** Max retries on busy lock. Default 5. */\n  retries?: number;\n  /** Backoff factor between retries. Default 1.5. */\n  retryFactor?: number;\n}\n\n/**\n * Run `fn` while holding an OS-level cross-process lock on `path`.\n *\n * If `proper-lockfile` is installed, uses it with a companion `<path>.lock`\n * file (`realpath: false`, so target file does NOT need to exist yet).\n * Otherwise falls back to in-process `withCwdMutex` and prints a one-shot\n * stderr warning telling the user to install `proper-lockfile` for\n * cross-process safety.\n *\n * The lock is released even when `fn` throws.\n *\n */\nexport async function withFileLock<T>(\n  path: string,\n  fn: () => Promise<T>,\n  options?: FileLockOptions,\n): Promise<T> {\n  const lib = await getProperLockfile();\n\n  if (lib === null) {\n    // #174 — stay silent when the structural check already explained itself. Emitting \"not\n    // installed\" on top of \"does not expose lock/unlock\" would be two contradictory diagnoses of\n    // one failure, and the reader has no way to tell which is true.\n    if (!warnedMissing && !warnedStructural) {\n      warnedMissing = true;\n      diag(describeLockLoadFailure(loadFailure));\n    }\n    return withCwdMutex(`file-lock:${path}`, fn);\n  }\n\n  // proper-lockfile errors immediately on same-process concurrent acquire\n  // (\"Lock file is already being held\"). Wrap with cwd-mutex first so\n  // in-process callers queue and only ONE thread at a time enters the\n  // cross-process acquire path. Combined: full in-process + cross-process\n  // serialization.\n  return withCwdMutex(`file-lock:${path}`, async () => {\n    const release = await lib.lock(path, {\n      // EC-1: companion lockfile, target path may not exist yet.\n      lockfilePath: `${path}.lock`,\n      realpath: false,\n      stale: options?.stale ?? 30_000,\n      retries: {\n        retries: options?.retries ?? 5,\n        factor: options?.retryFactor ?? 1.5,\n        minTimeout: 100,\n        maxTimeout: 5_000,\n      },\n    });\n\n    try {\n      return await fn();\n    } finally {\n      await release();\n    }\n  });\n}\n\n/**\n * Test helper — resets the cached proper-lockfile module + warning flag.\n * Allows tests to simulate \"module absent\" by clearing cache then\n * monkey-patching the dynamic import resolution.\n *\n * @internal\n */\nexport function _resetFileLockCacheForTesting(): void {\n  cached = undefined;\n  warnedMissing = false;\n}\n","/**\n * Durable JSONL primitives shared by the eval harness (M6).\n *\n * - `loadJsonl` — generic dataset reader (split/trim/skip-blank/parse) with a\n *   line-numbered {@link JsonlParseError}. The dataset SCHEMA is the caller's\n *   concern via `map` (M6 ADR D3) — this module owns only the parse.\n * - `appendJsonl` / `readJsonlIds` — crash-durable, resumable batch persistence\n *   (M6 ADR D1): each record is appended as one whole `\\n`-terminated line the\n *   instant it is produced, and a re-run resumes by skipping already-keyed rows.\n *\n * reference: knowledge-base/references/theocode-eval/lib/swebench-dataset.ts:82\n * (parseJsonl + line-N error) and swebench-batch.ts:113,205 (resume + per-line\n * flush).\n *\n * @internal\n */\nimport {\n  closeSync,\n  fstatSync,\n  mkdirSync,\n  openSync,\n  readFileSync,\n  readSync,\n  writeSync,\n} from \"node:fs\";\nimport { dirname } from \"node:path\";\n\n/** Raised when a JSONL line is not valid JSON or is not a JSON object. Carries the 1-based line number. */\nexport class JsonlParseError extends Error {\n  constructor(\n    message: string,\n    readonly line: number,\n  ) {\n    super(message);\n    this.name = \"JsonlParseError\";\n  }\n}\n\nfunction isPlainObject(value: unknown): value is Record<string, unknown> {\n  return typeof value === \"object\" && value !== null && !Array.isArray(value);\n}\n\n/** Parse a single trimmed line to a plain object, or `undefined` if blank / invalid / non-object. */\nfunction tryParseObjectLine(line: string): Record<string, unknown> | undefined {\n  if (line.length === 0) return undefined;\n  let parsed: unknown;\n  try {\n    parsed = JSON.parse(line);\n  } catch {\n    return undefined;\n  }\n  return isPlainObject(parsed) ? parsed : undefined;\n}\n\n/**\n * Parse a JSONL file into rows. Blank lines are skipped. A malformed or\n * non-object line throws {@link JsonlParseError} naming the 1-based line. When\n * `map` is provided, each raw object is mapped to the typed row (the SWE-bench\n * schema lives in the caller's `map`, per M6 ADR D3).\n */\nexport function loadJsonl<T = Record<string, unknown>>(\n  path: string,\n  opts: {\n    map?: (raw: Record<string, unknown>, lineNumber: number) => T;\n    /**\n     * M81 — tolerate a truncated LAST line (a crash artifact: the process died mid-write).\n     *\n     * Opt-in on purpose. As a default it would also swallow corruption in the MIDDLE of the file,\n     * turning loud data loss into silent data loss — the wrong trade for a session store.\n     */\n    tolerateTrailingPartialLine?: boolean;\n  } = {},\n): T[] {\n  const lines = readFileSync(path, \"utf8\").split(\"\\n\");\n  const out: T[] = [];\n  for (let i = 0; i < lines.length; i += 1) {\n    const lineNumber = i + 1;\n    const line = (lines[i] ?? \"\").trim();\n    if (line.length === 0) continue;\n    // M81 — `undefined` = a tolerated invalid line (the last one, truncated by a crash). Any other\n    // invalid line has already thrown inside `parseLine`.\n    const parsed = parseLine(\n      line,\n      lineNumber,\n      opts.tolerateTrailingPartialLine === true && lineNumber === lines.length,\n    );\n    if (parsed === undefined) break;\n    out.push(opts.map ? opts.map(parsed, lineNumber) : (parsed as unknown as T));\n  }\n  return out;\n}\n\n/**\n * Parses ONE line, returning `undefined` when it is a tolerated truncated last line.\n *\n * Extracted because `loadJsonl` went over the cognitive-complexity ceiling once it gained the\n * tolerance — and because parsing a line and iterating a file are two responsibilities that were\n * only together out of habit.\n */\nfunction parseLine(\n  line: string,\n  lineNumber: number,\n  tolerate: boolean,\n): Record<string, unknown> | undefined {\n  let parsed: unknown;\n  try {\n    parsed = JSON.parse(line);\n  } catch {\n    if (tolerate) return undefined;\n    throw new JsonlParseError(`line ${lineNumber}: invalid JSON`, lineNumber);\n  }\n  if (!isPlainObject(parsed)) {\n    throw new JsonlParseError(`line ${lineNumber}: not a JSON object`, lineNumber);\n  }\n  return parsed;\n}\n\n/**\n * Append one record as a whole `\\n`-terminated JSON line. Creates the parent dir\n * if missing. `appendFileSync` is synchronous, so within a single Node process\n * the event loop serializes writes and each call writes its line atomically —\n * interleave-safe for the bounded-concurrency batch runner.\n *\n * reference: swebench-batch.ts:192 (mkdir-before-append), :205 (per-line flush).\n */\nexport function appendJsonl(path: string, record: unknown): void {\n  // T2.4 — `0o700` for the same reason the file below is `0o600`, and it is the half M93 missed. A\n  // private file inside a group-writable directory can be replaced wholesale, and the replacement's\n  // mode is whatever the writer chose. Under `umask 002` this directory was born `0775`.\n  //\n  // The directory sits under `~/.theokit`, shared with the credential and trust stores, and the\n  // framework already wrote the diagnosis while fixing a sibling (`@theokit/agents\n  // config/trust-store.ts:157-161`): the mode argument is a no-op on a directory that already\n  // exists, \"and this one is shared with the SDK's transcript root — whoever creates it first sets\n  // the permissions\". Whoever creates it first is usually THIS function, because a session writes a\n  // transcript before it ever touches a credential. So `assertSecureModes` was not wrong to demand a\n  // private directory; this path was wrong to produce one that fails it, depending on run order.\n  //\n  // Creation-time only, deliberately: repairing a pre-existing directory means `stat` + `chmod` on\n  // every append, and this is the hot path of every session. The pre-existing case is what\n  // `assertSecureModes` is for.\n  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });\n  const prefix = needsLineBreakBefore(path) ? \"\\n\" : \"\";\n  // M93 (adversarial review, H1) — `0o600`. `appendFileSync` takes no `mode`, so the permission came\n  // from the umask: under `umask 022` the transcript was born `0664`, world-readable. The previous\n  // path (`replaceFileAtomic`) pinned `0o600` on purpose — \"holds the FULL in-flight content\n  // (credential snapshots, OAuth tokens)\" (`atomic-write.ts:107`) — and switching to append lost\n  // that silently. The same class had already been caught in the consumer (`atomic-sync.ts`, M88\n  // HIGH-1).\n  //\n  // `mode` only applies on CREATION; a pre-existing file keeps whatever permission it already has.\n  const fd = openSync(path, \"a\", 0o600);\n  try {\n    writeSync(fd, `${prefix}${JSON.stringify(record)}\\n`);\n  } finally {\n    closeSync(fd);\n  }\n}\n\n/**\n * Does the file end without a `\\n`? Then the last line is truncated — a crash mid-append.\n *\n * Without this check the next append **glues** itself onto the middle of the broken line, producing\n * an invalid line the reader discards: the NEW record disappears along with the partial one. The\n * previous path (read-modify-write) self-healed from this because it rewrote the whole file.\n * Measured in M93's adversarial review (H2): after an append over a truncated file, the\n * just-written record was no longer readable.\n *\n * Reads **one byte**, not the file.\n */\nfunction needsLineBreakBefore(path: string): boolean {\n  let fd: number;\n  try {\n    fd = openSync(path, \"r\");\n  } catch {\n    return false; // the file does not exist yet: nothing to splice onto\n  }\n  try {\n    const size = fstatSync(fd).size;\n    if (size === 0) return false;\n    const buf = Buffer.alloc(1);\n    readSync(fd, buf, 0, 1, size - 1);\n    return buf[0] !== 0x0a;\n  } finally {\n    closeSync(fd);\n  }\n}\n\n/**\n * Read the set of keys from an existing JSONL file for which `keyFn(parsed)`\n * returns a non-empty string. Used to resume a crashed batch by skipping rows\n * already persisted with a successful result. A trailing partial line from an\n * interrupted append is tolerated (skipped, not thrown), and a missing file\n * yields an empty set.\n *\n * reference: swebench-batch.ts:113 (readDoneIds), :129 (success-only),\n * :131 (tolerate partial line).\n */\nexport function readJsonlIds(\n  path: string,\n  keyFn: (parsed: Record<string, unknown>) => string | undefined,\n): Set<string> {\n  const done = new Set<string>();\n  let text: string;\n  try {\n    text = readFileSync(path, \"utf8\");\n  } catch {\n    return done; // no file yet → nothing done\n  }\n  for (const rawLine of text.split(\"\\n\")) {\n    // A trailing partial line from an interrupted run parses to undefined → skipped.\n    const parsed = tryParseObjectLine(rawLine.trim());\n    if (parsed === undefined) continue;\n    const key = keyFn(parsed);\n    if (typeof key === \"string\" && key.length > 0) done.add(key);\n  }\n  return done;\n}\n"]}

package/dist/{chunk-R3UPQFKK.cjs → chunk-V2BOS4WF.cjs}

@@ -1,12 +1,12 @@
 'use strict';
 
 var chunkVKJ7V7EB_cjs = require('./chunk-VKJ7V7EB.cjs');
-var chunkK3FW2XZD_cjs = require('./chunk-K3FW2XZD.cjs');
+var chunk4ZHTIJNE_cjs = require('./chunk-4ZHTIJNE.cjs');
 var crypto = require('crypto');
 var fs = require('fs');
 var path = require('path');
 
-var PathTraversalError = class extends chunkK3FW2XZD_cjs.ConfigurationError {
+var PathTraversalError = class extends chunk4ZHTIJNE_cjs.ConfigurationError {
   name = "PathTraversalError";
   constructor(input, resolvedPath) {
     super(`Path traversal attempt: ${input} \u2192 ${resolvedPath}`, {
@@ -14,7 +14,7 @@ var PathTraversalError = class extends chunkK3FW2XZD_cjs.ConfigurationError {
     });
   }
 };
-var ForbiddenPathError = class extends chunkK3FW2XZD_cjs.ConfigurationError {
+var ForbiddenPathError = class extends chunk4ZHTIJNE_cjs.ConfigurationError {
   name = "ForbiddenPathError";
   constructor(path) {
     super(
@@ -188,18 +188,18 @@ function rejectParentTraversal(input, normalized) {
 function sanitizeIdentifier(input, options) {
   const maxLen = options?.maxLen ?? 64;
   if (input.length === 0 || input.length > maxLen) {
-    throw new chunkK3FW2XZD_cjs.ConfigurationError(`Identifier length out of range (1-${maxLen}): "${input}"`, {
+    throw new chunk4ZHTIJNE_cjs.ConfigurationError(`Identifier length out of range (1-${maxLen}): "${input}"`, {
       code: "invalid_identifier"
     });
   }
   const controlChar = firstControlCharLabel(input);
   if (controlChar !== void 0) {
-    throw new chunkK3FW2XZD_cjs.ConfigurationError(`Identifier contains ${controlChar}: "${input}"`, {
+    throw new chunk4ZHTIJNE_cjs.ConfigurationError(`Identifier contains ${controlChar}: "${input}"`, {
       code: "invalid_identifier"
     });
   }
   if (!IDENTIFIER_PATTERN.test(input)) {
-    throw new chunkK3FW2XZD_cjs.ConfigurationError(`Identifier contains invalid characters: "${input}"`, {
+    throw new chunk4ZHTIJNE_cjs.ConfigurationError(`Identifier contains invalid characters: "${input}"`, {
       code: "invalid_identifier"
     });
   }
@@ -207,7 +207,7 @@ function sanitizeIdentifier(input, options) {
 }
 function safeFilenameForId(id, options) {
   if (id.length === 0) {
-    throw new chunkK3FW2XZD_cjs.ConfigurationError("Filename id must be a non-empty string", {
+    throw new chunk4ZHTIJNE_cjs.ConfigurationError("Filename id must be a non-empty string", {
       code: "invalid_filename_id"
     });
   }
@@ -227,5 +227,5 @@ exports.safeFilenameForId = safeFilenameForId;
 exports.safePathJoin = safePathJoin;
 exports.sanitizeIdentifier = sanitizeIdentifier;
 exports.validateArtifactPath = validateArtifactPath;
-//# sourceMappingURL=chunk-R3UPQFKK.cjs.map
-//# sourceMappingURL=chunk-R3UPQFKK.cjs.map
+//# sourceMappingURL=chunk-V2BOS4WF.cjs.map
+//# sourceMappingURL=chunk-V2BOS4WF.cjs.map

package/dist/{chunk-R3UPQFKK.cjs.map → chunk-V2BOS4WF.cjs.map}

@@ -1 +1 @@
-{"version":3,"sources":["../src/internal/security/path-guard.ts"],"names":["ConfigurationError","atOrInsideRoot","resolve","path","realpathSync","lstatSync","readlinkSync","dirname","createHash"],"mappings":"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","file":"chunk-R3UPQFKK.cjs","sourcesContent":["/**\n * Canonical path-guard module (ADRs D79-D81).\n *\n * Three primitives + one typed error:\n *   - `safePathJoin(base, ...parts)` — resolve THEN prefix-check (ADR D80).\n *   - `assertNoSymlinkEscape(path, base)` — `realpathSync` resolves entire\n *     symlink chain (EC-1 fix; Hermes v0.2 #386, #61).\n *   - `sanitizeIdentifier(input, { maxLen })` — strict grammar\n *     `^[a-z0-9][a-z0-9-_]*$` (ADR D81; case-insensitive on input,\n *     lowercase on output).\n *   - `PathTraversalError` — extends ConfigurationError with code\n *     `path_traversal` (ADR D65: no new hierarchy).\n *\n * Wire at all sites where user input becomes a path. CI lint gate\n * `tests/lint/no-unguarded-path-input.test.ts` prevents regression\n * (ADR D85).\n *\n * @internal\n */\n\nimport { createHash } from \"node:crypto\";\nimport { lstatSync, readlinkSync, realpathSync, type Stats } from \"node:fs\";\nimport { dirname, resolve } from \"node:path\";\n\nimport { ConfigurationError } from \"../../errors.js\";\nimport { atOrInsideRoot } from \"../runtime/context/path-containment.js\";\n\n/**\n * Thrown when a path operation would escape its allowed base directory.\n * Extends `ConfigurationError` (no new error hierarchy per ADR D65).\n *\n */\nexport class PathTraversalError extends ConfigurationError {\n  override readonly name: string = \"PathTraversalError\";\n\n  constructor(input: string, resolvedPath: string) {\n    super(`Path traversal attempt: ${input} → ${resolvedPath}`, {\n      code: \"path_traversal\",\n    });\n  }\n}\n\n/**\n * Thrown when an agent tool is asked to read or write a sensitive path\n * that the blocklist forbids (`.env`, `.git/`, `node_modules/`, `.theo/`,\n * lock files). Distinct from `PathTraversalError` because the path is\n * lexically inside the project — it is just sensitive.\n *\n * Extends `ConfigurationError` (no new error hierarchy per ADR D65).\n *\n * @public\n */\nexport class ForbiddenPathError extends ConfigurationError {\n  override readonly name: string = \"ForbiddenPathError\";\n\n  constructor(path: string) {\n    super(\n      `Path '${path}' is in the sensitive-file blocklist (.env, .git/, node_modules/, .theo/, lock files)`,\n      {\n        code: \"forbidden_path\",\n      },\n    );\n  }\n}\n\n/**\n * Is `target` the same as `base`, or strictly under it?\n *\n * The prefix must not double the separator. `resolve` strips a trailing `sep` from every base\n * EXCEPT the filesystem root, where `resolve(sep) === sep`; there `base + sep` would be `//`, which\n * no absolute path starts with, so a root base rejected EVERY path (#149). Only the root takes that\n * branch — for any other base the prefix is unchanged, so containment is not weakened.\n *\n * Both containment checks in this module go through here: they had the same defect and were fixed\n * one at a time, which is exactly how the two drifted apart in the first place.\n *\n * Both arguments MUST already be resolved absolute paths.\n */\nfunction isInside(target: string, base: string): boolean {\n  // B-117 — compared after symlink resolution, via the shared rule. A prefix test judges a link by\n  // its NAME: `<base>/link/x` where `link` points outside is lexically inside and physically not.\n  // Measured reachable from the plugin manager and the MCP client before this was changed.\n  //\n  // The root itself stays allowed, which `insideRoot` alone does not answer: it returns false for\n  // `target === base` (correct for its own caller, wrong here, where `safePathJoin(base)` with no\n  // parts must return `base`). Kept as an explicit second clause rather than by weakening the\n  // shared rule for everyone.\n  return atOrInsideRoot(target, base);\n}\n\n/**\n * Join `base` with `...parts` and ensure the resolved absolute path stays\n * under `base`. Resolves FIRST, then prefix-checks (ADR D80) — prevents\n * normalized-escape bypasses like `subdir/.\\\\./bar`.\n *\n * Returns the safe absolute path. Throws `PathTraversalError` if escape.\n *\n */\nexport function safePathJoin(base: string, ...parts: string[]): string {\n  if (base === \"\") {\n    throw new Error(\"safePathJoin: base must be non-empty\");\n  }\n  // T5.5 — NUL byte + C0/DEL control char rejection at the boundary.\n  // Apply before path resolution so a malicious input never reaches\n  // `resolve` (which on some platforms behaved unexpectedly with NUL\n  // and in N-API callers historically silently truncated).\n  rejectNulAndControlChars(base, \"base\");\n  for (const part of parts) {\n    rejectNulAndControlChars(part, \"path segment\");\n  }\n  const baseResolved = resolve(base);\n  const target = resolve(base, ...parts);\n  if (!isInside(target, baseResolved)) {\n    throw new PathTraversalError(parts.join(\"/\"), target);\n  }\n  return target;\n}\n\n/**\n * T5.5 — the operator-legible label for the first NUL (`\\x00`), C0 control char (`\\x01-\\x1F`) or\n * DEL (`\\x7F`) in `input`, or `undefined` when it carries none. Centralizes the scan so every\n * public path-guard / sanitize entrypoint shares one definition of \"control character\".\n *\n * Detection is separated from the throw so the two callers can share the scan and the precise\n * diagnostic while each raising the error ITS OWN contract documents (#368) — a path guard reports\n * a traversal, an identifier validator reports an invalid identifier. Before that split both threw\n * `PathTraversalError`, which made an identifier validator's error class depend on the bytes of the\n * input it was handed.\n *\n * @internal\n */\nfunction firstControlCharLabel(input: string): string | undefined {\n  for (let i = 0; i < input.length; i++) {\n    const code = input.charCodeAt(i);\n    if (code === 0x00 || (code >= 0x01 && code <= 0x1f) || code === 0x7f) {\n      return code === 0x00 ? \"<nul-byte>\" : `<control-char-0x${code.toString(16)}>`;\n    }\n  }\n  return undefined;\n}\n\n/**\n * Reject any path-shaped input carrying a NUL or control character, as `PathTraversalError` — the\n * same shape as every other path-shape rejection, so callers do not learn a second error class.\n *\n * @internal\n */\nfunction rejectNulAndControlChars(input: string, role: string): void {\n  const label = firstControlCharLabel(input);\n  if (label !== undefined) throw new PathTraversalError(`${role}: ${input}`, label);\n}\n\n/**\n * Assert that `path` — including every directory component in the chain —\n * stays under `base` after symlink resolution. No-op when nothing on the\n * path exists yet.\n *\n * Two-bug history:\n *   1. **EC-1** (original fix, kept): a multi-level symlink chain A → B → C\n *      must be resolved end-to-end. `realpathSync` does this in 1 syscall.\n *   2. **Defence-in-depth** (added v1.x): the previous implementation only\n *      called `lstatSync(path)` on the terminal component. If an INTERMEDIATE\n *      directory was a symlink (`base/inner-symlink → /outside`), `lstat` on\n *      `base/inner-symlink/file.txt` followed the symlink and reported the\n *      regular file — escape went undetected. Fix: walk up to the nearest\n *      existing ancestor and `realpath` THAT, then re-attach the suffix and\n *      check the result against the canonical base.\n *\n */\nexport function assertNoSymlinkEscape(path: string, base: string): void {\n  // T5.5 — reject NUL / control chars before any FS call (a NUL byte\n  // in the path used to silently truncate at the C boundary on legacy\n  // libc — defense in depth even on modern Node).\n  rejectNulAndControlChars(path, \"path\");\n  rejectNulAndControlChars(base, \"base\");\n  // Canonical base — symlinks in the base path itself are absorbed once here.\n  let baseResolved: string;\n  try {\n    baseResolved = realpathSync(base);\n  } catch {\n    // base doesn't exist as a real directory yet — fall back to lexical resolve.\n    baseResolved = resolve(base);\n  }\n\n  // Find the deepest ancestor of `path` that exists, then realpath it.\n  // Anything from there onward is \"not yet on disk\" and contributes only\n  // its lexical suffix. This covers three cases:\n  //   - path exists (regular file or symlink at any depth) → realpath the full path\n  //   - path doesn't exist but intermediate dir is a symlink → realpath the ancestor\n  //   - nothing on the path exists → no escape risk (return)\n  const resolved = realpathOfDeepestExisting(path);\n  if (resolved === undefined) return; // path has no existing prefix — nothing to attack\n\n  if (!isInside(resolved, baseResolved)) {\n    throw new PathTraversalError(`symlink ${path}`, resolved);\n  }\n}\n\n/**\n * Find the deepest ancestor of `path` that exists on disk, resolve all\n * symlinks in that ancestor via `realpathSync`, and re-attach the\n * lexical suffix. Returns `undefined` when no ancestor exists.\n *\n * Handles dangling symlinks: if the terminal IS a symlink but its target\n * is missing, we still detect escape via `readlinkSync` + parent resolve.\n */\nfunction realpathOfDeepestExisting(path: string): string | undefined {\n  // First try the full path — the common case.\n  try {\n    return realpathSync(path);\n  } catch {\n    // Not resolvable. Two sub-cases.\n  }\n\n  // Sub-case A: terminal is a dangling symlink.\n  try {\n    const stat: Stats = lstatSync(path);\n    if (stat.isSymbolicLink()) {\n      const target = readlinkSync(path);\n      // Resolve target relative to the REAL parent dir, so intermediate\n      // symlinks in the parent chain are absorbed.\n      const parentReal = realpathOfDeepestExisting(dirname(path));\n      const parentBase = parentReal ?? dirname(path);\n      return resolve(parentBase, target);\n    }\n  } catch {\n    // lstat failed too — terminal doesn't exist at all.\n  }\n\n  // Sub-case B: walk up to the nearest existing ancestor, then re-attach\n  // the suffix lexically.\n  let cursor = dirname(path);\n  let suffix = path.slice(cursor.length);\n  while (cursor !== dirname(cursor)) {\n    try {\n      const real = realpathSync(cursor);\n      // Reconstruct: ancestor's realpath + remaining (still-lexical) suffix\n      return resolve(real, `.${suffix}`);\n    } catch {\n      suffix = path.slice(dirname(cursor).length);\n      cursor = dirname(cursor);\n    }\n  }\n  // Reached filesystem root without finding any existing ancestor.\n  return undefined;\n}\n\nconst LOCK_FILES = new Set([\"pnpm-lock.yaml\", \"package-lock.json\", \"yarn.lock\", \"bun.lockb\"]);\n\n// T5.6 — top-level credential dot-dirs / dot-files. Matching against\n// the FIRST path segment (lowercase). Adding any entry here costs a\n// CHANGELOG note + an explicit case-fold test (entries are lowercased\n// at module load).\nconst SENSITIVE_FIRST_SEGMENTS = new Set([\n  \".ssh\",\n  \".aws\",\n  \".docker\",\n  \".kube\",\n  \".npmrc\",\n  \".netrc\",\n  \".pgpass\",\n]);\n\n// T5.6 — credential basenames blocked at ANY depth (lowercase). Catches\n// the developer-laptop case where an agent recurses into a subdir.\nconst SENSITIVE_BASENAMES = new Set([\n  \"id_rsa\",\n  \"id_ed25519\",\n  \"id_ecdsa\",\n  \"id_dsa\",\n  \"authorized_keys\",\n  \"known_hosts\",\n  \".npmrc\",\n  \".netrc\",\n  \".pgpass\",\n]);\n\n// T5.6 — extension suffixes blocked at ANY depth (lowercase). Covers\n// the entire `*.pem` / `*.key` private-material family.\nconst SENSITIVE_SUFFIXES = [\".pem\", \".key\", \".p12\", \".pfx\"];\n\n/**\n * Decide whether a project-relative path points to a known-sensitive file\n * that a coding agent must not read or write.\n *\n * Universal blocklist (works for any agent operating on a project tree):\n *\n *   - `.env`, `.env.<anything>` — except `.env.example` (template safe to read)\n *   - `.git/` — version control internals\n *   - `node_modules/` — dependency cache (changes don't belong to the user)\n *   - `.theo/` — TheoKit build artefacts / state\n *   - Lock files at any depth: `pnpm-lock.yaml`, `package-lock.json`,\n *     `yarn.lock`, `bun.lockb`\n *\n * Operates on path segments (forward-slash normalized). Cross-platform safe.\n *\n * Use together with `safePathJoin` + `assertNoSymlinkEscape`: the former two\n * defeat traversal, this one defeats reading a file that is lexically inside\n * the project but should not be agent-visible.\n *\n * @public\n */\nexport function isForbiddenPath(input: string): boolean {\n  // T5.6 — lowercase normalization defeats case-only bypass on\n  // case-insensitive filesystems (Windows/macOS-default) where `.ENV`\n  // and `.env` map to the same inode but a case-sensitive string\n  // check passes the former.\n  const normalized = input.replace(/\\\\/g, \"/\").replace(/^\\.\\//, \"\").toLowerCase();\n  if (normalized.length === 0) return false;\n\n  const segments = normalized.split(\"/\").filter((s) => s.length > 0);\n  if (segments.length === 0) return false;\n\n  if (isForbiddenFirstSegment(segments[0]!)) return true;\n  if (isForbiddenBasename(segments[segments.length - 1]!)) return true;\n  return false;\n}\n\nfunction isForbiddenFirstSegment(first: string): boolean {\n  // .env.example is explicitly allowlisted (template safe to read)\n  if (first === \".env.example\") return false;\n  if (first === \".env\") return true;\n  if (/^\\.env\\./.test(first)) return true;\n  if (first === \".git\" || first === \"node_modules\" || first === \".theo\") return true;\n  return SENSITIVE_FIRST_SEGMENTS.has(first);\n}\n\nfunction isForbiddenBasename(basename: string): boolean {\n  if (LOCK_FILES.has(basename)) return true;\n  if (SENSITIVE_BASENAMES.has(basename)) return true;\n  for (const suffix of SENSITIVE_SUFFIXES) {\n    if (basename.endsWith(suffix)) return true;\n  }\n  return false;\n}\n\nconst IDENTIFIER_PATTERN = /^[a-z0-9][a-z0-9\\-_]*$/i;\n\n/**\n * T1.4 — validate a relative artifact path string BEFORE it is used to look\n * up a fixture or to fetch from PaaS. Rejects every well-known traversal\n * vector at the boundary, throwing `PathTraversalError`.\n *\n * Vectors rejected:\n *  - classic `..` parent-directory traversal (any segment).\n *  - backslash separators (Windows-style `..\\\\windows`).\n *  - URL-encoded `%2e%2e` / `%2E%2E` (double-decoded traversal).\n *  - NUL byte injection (`\\x00`).\n *  - Windows drive letter prefix (`C:`, `D:\\\\...`).\n *  - Home-tilde expansion (`~/`, `~root/...`).\n *  - Absolute paths starting with `/`.\n *\n * Does NOT touch the filesystem — the call is shape-only. Live symlink\n * traversal protection happens via `assertNoSymlinkEscape` at the FS-resolve\n * boundary.\n *\n * @param input - Caller-supplied artifact path.\n * @throws `PathTraversalError` on any rejection.\n *\n * Semver-exempt: reachable via the `@theokit/sdk/internal/security` sub-path, which the package\n * declares in `exports` but does NOT cover with its semver contract.\n */\nexport function validateArtifactPath(input: string): void {\n  rejectKnownPrefixVectors(input);\n  const normalized = decodeAndNormalize(input);\n  rejectParentTraversal(input, normalized);\n}\n\nfunction rejectKnownPrefixVectors(input: string): void {\n  if (input.includes(\"\\x00\")) {\n    throw new PathTraversalError(input, \"<nul-byte>\");\n  }\n  if (input.startsWith(\"/\") || input.startsWith(\"~\")) {\n    throw new PathTraversalError(input, input);\n  }\n  if (/^[A-Za-z]:[\\\\/]?/.test(input)) {\n    throw new PathTraversalError(input, input);\n  }\n}\n\nfunction decodeAndNormalize(input: string): string {\n  // URL-encoded traversal — 2 passes catches `%252e%252e`.\n  // Malformed sequences (decodeURIComponent throws) are themselves a rejection.\n  let decoded = input;\n  for (let i = 0; i < 2; i += 1) {\n    try {\n      const next = decodeURIComponent(decoded);\n      if (next === decoded) break;\n      decoded = next;\n    } catch {\n      throw new PathTraversalError(input, \"<malformed-url-encoding>\");\n    }\n  }\n  // Normalize backslash to forward slash before segment-walking.\n  return decoded.replace(/\\\\/g, \"/\");\n}\n\nfunction rejectParentTraversal(input: string, normalized: string): void {\n  for (const segment of normalized.split(\"/\")) {\n    if (segment === \"..\" || segment === \"..%00\") {\n      throw new PathTraversalError(input, normalized);\n    }\n  }\n  // Defense in depth: literal `..` anywhere in the normalized string.\n  if (normalized.includes(\"..\")) {\n    throw new PathTraversalError(input, normalized);\n  }\n}\n\n/**\n * Validate that `input` is a safe path component (skill name, agent ID,\n * namespace, etc.) and return its lowercase form. Strict grammar\n * `^[a-z0-9][a-z0-9-_]*$` rejects path separators, dots, null bytes,\n * whitespace, unicode invisible chars, and any leading `-`/`_`.\n *\n * ONE error class leaves this function: `ConfigurationError` with code\n * `invalid_identifier`, for every rejection — length out of range, a path\n * separator, `..`, a space, a leading `-`, and a NUL / C0 control char / DEL\n * alike. A caller can branch on that code and know it has covered the whole\n * rejection surface.\n *\n * Before #368 the control-char branch threw `PathTraversalError` instead, which\n * made the error CLASS a function of the attacker's bytes; the message still names\n * the offending byte, which is the part that was worth keeping.\n *\n * @param input - User-supplied identifier candidate.\n * @param options.maxLen - Maximum allowed length (default 64).\n * @returns Lowercase form of `input`.\n * @throws `ConfigurationError` with code `invalid_identifier` on every rejection.\n */\nexport function sanitizeIdentifier(input: string, options?: { maxLen?: number }): string {\n  const maxLen = options?.maxLen ?? 64;\n  if (input.length === 0 || input.length > maxLen) {\n    throw new ConfigurationError(`Identifier length out of range (1-${maxLen}): \"${input}\"`, {\n      code: \"invalid_identifier\",\n    });\n  }\n  // T5.5 — explicit NUL / control char rejection ahead of the generic pattern check. The\n  // IDENTIFIER_PATTERN regex already excludes these (they are not in `[a-z0-9\\-_]`); naming the\n  // offending byte gives operators a precise diagnostic instead of the generic \"invalid characters\"\n  // message, which is what makes a prompt-injection trace legible (Rule 3).\n  //\n  // #368 — the diagnostic used to arrive as a `PathTraversalError`, because the branch reused\n  // `safePathJoin`'s thrower. That made the error CLASS a function of the attacker's bytes: a\n  // caller branching on the documented `invalid_identifier` rethrew for any input carrying a\n  // control char, so a rejection surfaced as a 500 and the 400/500 split became an oracle. The\n  // detection is shared; the error each contract documents is not.\n  const controlChar = firstControlCharLabel(input);\n  if (controlChar !== undefined) {\n    throw new ConfigurationError(`Identifier contains ${controlChar}: \"${input}\"`, {\n      code: \"invalid_identifier\",\n    });\n  }\n  if (!IDENTIFIER_PATTERN.test(input)) {\n    throw new ConfigurationError(`Identifier contains invalid characters: \"${input}\"`, {\n      code: \"invalid_identifier\",\n    });\n  }\n  return input.toLowerCase();\n}\n\n/**\n * Convert ANY opaque id (agent id, run id, conversation id, namespace, email,\n * arbitrary string) into a deterministic, filesystem-safe filename component.\n *\n * Unlike {@link sanitizeIdentifier} (which THROWS on non-conforming input),\n * this is a total function: it NEVER throws on a non-empty string. It returns\n * the lowercased id verbatim when it already matches the safe grammar\n * `^[a-z0-9][a-z0-9-_]*$` and fits `maxLen` (so UUIDs, hashes, and slugs stay\n * human-readable), otherwise a deterministic `h-<16 hex>` sha256 token\n * (collision-resistant and always a valid filename). The output charset is\n * always `[a-z0-9_-]`, safe as a literal path segment on every filesystem.\n *\n * @param id - any opaque identifier (must be a non-empty string)\n * @param options.maxLen - max length for the passthrough branch (default 128).\n *   Ids longer than this are hashed; the hash token itself is always short.\n * @throws ConfigurationError (code `invalid_filename_id`) only on empty input.\n *\n * @example\n *   safeFilenameForId(\"550e8400-e29b-41d4-a716-446655440000\") // passthrough\n *   safeFilenameForId(\"user@example.com\")                      // \"h-<16hex>\"\n *\n */\nexport function safeFilenameForId(id: string, options?: { maxLen?: number }): string {\n  if (id.length === 0) {\n    throw new ConfigurationError(\"Filename id must be a non-empty string\", {\n      code: \"invalid_filename_id\",\n    });\n  }\n  const maxLen = options?.maxLen ?? 128;\n  const lower = id.toLowerCase();\n  if (lower.length <= maxLen && IDENTIFIER_PATTERN.test(lower)) {\n    return lower;\n  }\n  return `h-${createHash(\"sha256\").update(id).digest(\"hex\").slice(0, 16)}`;\n}\n"]}
+{"version":3,"sources":["../src/internal/security/path-guard.ts"],"names":["ConfigurationError","atOrInsideRoot","resolve","path","realpathSync","lstatSync","readlinkSync","dirname","createHash"],"mappings":"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","file":"chunk-V2BOS4WF.cjs","sourcesContent":["/**\n * Canonical path-guard module (ADRs D79-D81).\n *\n * Three primitives + one typed error:\n *   - `safePathJoin(base, ...parts)` — resolve THEN prefix-check (ADR D80).\n *   - `assertNoSymlinkEscape(path, base)` — `realpathSync` resolves entire\n *     symlink chain (EC-1 fix; Hermes v0.2 #386, #61).\n *   - `sanitizeIdentifier(input, { maxLen })` — strict grammar\n *     `^[a-z0-9][a-z0-9-_]*$` (ADR D81; case-insensitive on input,\n *     lowercase on output).\n *   - `PathTraversalError` — extends ConfigurationError with code\n *     `path_traversal` (ADR D65: no new hierarchy).\n *\n * Wire at all sites where user input becomes a path. CI lint gate\n * `tests/lint/no-unguarded-path-input.test.ts` prevents regression\n * (ADR D85).\n *\n * @internal\n */\n\nimport { createHash } from \"node:crypto\";\nimport { lstatSync, readlinkSync, realpathSync, type Stats } from \"node:fs\";\nimport { dirname, resolve } from \"node:path\";\n\nimport { ConfigurationError } from \"../../errors.js\";\nimport { atOrInsideRoot } from \"../runtime/context/path-containment.js\";\n\n/**\n * Thrown when a path operation would escape its allowed base directory.\n * Extends `ConfigurationError` (no new error hierarchy per ADR D65).\n *\n */\nexport class PathTraversalError extends ConfigurationError {\n  override readonly name: string = \"PathTraversalError\";\n\n  constructor(input: string, resolvedPath: string) {\n    super(`Path traversal attempt: ${input} → ${resolvedPath}`, {\n      code: \"path_traversal\",\n    });\n  }\n}\n\n/**\n * Thrown when an agent tool is asked to read or write a sensitive path\n * that the blocklist forbids (`.env`, `.git/`, `node_modules/`, `.theo/`,\n * lock files). Distinct from `PathTraversalError` because the path is\n * lexically inside the project — it is just sensitive.\n *\n * Extends `ConfigurationError` (no new error hierarchy per ADR D65).\n *\n * @public\n */\nexport class ForbiddenPathError extends ConfigurationError {\n  override readonly name: string = \"ForbiddenPathError\";\n\n  constructor(path: string) {\n    super(\n      `Path '${path}' is in the sensitive-file blocklist (.env, .git/, node_modules/, .theo/, lock files)`,\n      {\n        code: \"forbidden_path\",\n      },\n    );\n  }\n}\n\n/**\n * Is `target` the same as `base`, or strictly under it?\n *\n * The prefix must not double the separator. `resolve` strips a trailing `sep` from every base\n * EXCEPT the filesystem root, where `resolve(sep) === sep`; there `base + sep` would be `//`, which\n * no absolute path starts with, so a root base rejected EVERY path (#149). Only the root takes that\n * branch — for any other base the prefix is unchanged, so containment is not weakened.\n *\n * Both containment checks in this module go through here: they had the same defect and were fixed\n * one at a time, which is exactly how the two drifted apart in the first place.\n *\n * Both arguments MUST already be resolved absolute paths.\n */\nfunction isInside(target: string, base: string): boolean {\n  // B-117 — compared after symlink resolution, via the shared rule. A prefix test judges a link by\n  // its NAME: `<base>/link/x` where `link` points outside is lexically inside and physically not.\n  // Measured reachable from the plugin manager and the MCP client before this was changed.\n  //\n  // The root itself stays allowed, which `insideRoot` alone does not answer: it returns false for\n  // `target === base` (correct for its own caller, wrong here, where `safePathJoin(base)` with no\n  // parts must return `base`). Kept as an explicit second clause rather than by weakening the\n  // shared rule for everyone.\n  return atOrInsideRoot(target, base);\n}\n\n/**\n * Join `base` with `...parts` and ensure the resolved absolute path stays\n * under `base`. Resolves FIRST, then prefix-checks (ADR D80) — prevents\n * normalized-escape bypasses like `subdir/.\\\\./bar`.\n *\n * Returns the safe absolute path. Throws `PathTraversalError` if escape.\n *\n */\nexport function safePathJoin(base: string, ...parts: string[]): string {\n  if (base === \"\") {\n    throw new Error(\"safePathJoin: base must be non-empty\");\n  }\n  // T5.5 — NUL byte + C0/DEL control char rejection at the boundary.\n  // Apply before path resolution so a malicious input never reaches\n  // `resolve` (which on some platforms behaved unexpectedly with NUL\n  // and in N-API callers historically silently truncated).\n  rejectNulAndControlChars(base, \"base\");\n  for (const part of parts) {\n    rejectNulAndControlChars(part, \"path segment\");\n  }\n  const baseResolved = resolve(base);\n  const target = resolve(base, ...parts);\n  if (!isInside(target, baseResolved)) {\n    throw new PathTraversalError(parts.join(\"/\"), target);\n  }\n  return target;\n}\n\n/**\n * T5.5 — the operator-legible label for the first NUL (`\\x00`), C0 control char (`\\x01-\\x1F`) or\n * DEL (`\\x7F`) in `input`, or `undefined` when it carries none. Centralizes the scan so every\n * public path-guard / sanitize entrypoint shares one definition of \"control character\".\n *\n * Detection is separated from the throw so the two callers can share the scan and the precise\n * diagnostic while each raising the error ITS OWN contract documents (#368) — a path guard reports\n * a traversal, an identifier validator reports an invalid identifier. Before that split both threw\n * `PathTraversalError`, which made an identifier validator's error class depend on the bytes of the\n * input it was handed.\n *\n * @internal\n */\nfunction firstControlCharLabel(input: string): string | undefined {\n  for (let i = 0; i < input.length; i++) {\n    const code = input.charCodeAt(i);\n    if (code === 0x00 || (code >= 0x01 && code <= 0x1f) || code === 0x7f) {\n      return code === 0x00 ? \"<nul-byte>\" : `<control-char-0x${code.toString(16)}>`;\n    }\n  }\n  return undefined;\n}\n\n/**\n * Reject any path-shaped input carrying a NUL or control character, as `PathTraversalError` — the\n * same shape as every other path-shape rejection, so callers do not learn a second error class.\n *\n * @internal\n */\nfunction rejectNulAndControlChars(input: string, role: string): void {\n  const label = firstControlCharLabel(input);\n  if (label !== undefined) throw new PathTraversalError(`${role}: ${input}`, label);\n}\n\n/**\n * Assert that `path` — including every directory component in the chain —\n * stays under `base` after symlink resolution. No-op when nothing on the\n * path exists yet.\n *\n * Two-bug history:\n *   1. **EC-1** (original fix, kept): a multi-level symlink chain A → B → C\n *      must be resolved end-to-end. `realpathSync` does this in 1 syscall.\n *   2. **Defence-in-depth** (added v1.x): the previous implementation only\n *      called `lstatSync(path)` on the terminal component. If an INTERMEDIATE\n *      directory was a symlink (`base/inner-symlink → /outside`), `lstat` on\n *      `base/inner-symlink/file.txt` followed the symlink and reported the\n *      regular file — escape went undetected. Fix: walk up to the nearest\n *      existing ancestor and `realpath` THAT, then re-attach the suffix and\n *      check the result against the canonical base.\n *\n */\nexport function assertNoSymlinkEscape(path: string, base: string): void {\n  // T5.5 — reject NUL / control chars before any FS call (a NUL byte\n  // in the path used to silently truncate at the C boundary on legacy\n  // libc — defense in depth even on modern Node).\n  rejectNulAndControlChars(path, \"path\");\n  rejectNulAndControlChars(base, \"base\");\n  // Canonical base — symlinks in the base path itself are absorbed once here.\n  let baseResolved: string;\n  try {\n    baseResolved = realpathSync(base);\n  } catch {\n    // base doesn't exist as a real directory yet — fall back to lexical resolve.\n    baseResolved = resolve(base);\n  }\n\n  // Find the deepest ancestor of `path` that exists, then realpath it.\n  // Anything from there onward is \"not yet on disk\" and contributes only\n  // its lexical suffix. This covers three cases:\n  //   - path exists (regular file or symlink at any depth) → realpath the full path\n  //   - path doesn't exist but intermediate dir is a symlink → realpath the ancestor\n  //   - nothing on the path exists → no escape risk (return)\n  const resolved = realpathOfDeepestExisting(path);\n  if (resolved === undefined) return; // path has no existing prefix — nothing to attack\n\n  if (!isInside(resolved, baseResolved)) {\n    throw new PathTraversalError(`symlink ${path}`, resolved);\n  }\n}\n\n/**\n * Find the deepest ancestor of `path` that exists on disk, resolve all\n * symlinks in that ancestor via `realpathSync`, and re-attach the\n * lexical suffix. Returns `undefined` when no ancestor exists.\n *\n * Handles dangling symlinks: if the terminal IS a symlink but its target\n * is missing, we still detect escape via `readlinkSync` + parent resolve.\n */\nfunction realpathOfDeepestExisting(path: string): string | undefined {\n  // First try the full path — the common case.\n  try {\n    return realpathSync(path);\n  } catch {\n    // Not resolvable. Two sub-cases.\n  }\n\n  // Sub-case A: terminal is a dangling symlink.\n  try {\n    const stat: Stats = lstatSync(path);\n    if (stat.isSymbolicLink()) {\n      const target = readlinkSync(path);\n      // Resolve target relative to the REAL parent dir, so intermediate\n      // symlinks in the parent chain are absorbed.\n      const parentReal = realpathOfDeepestExisting(dirname(path));\n      const parentBase = parentReal ?? dirname(path);\n      return resolve(parentBase, target);\n    }\n  } catch {\n    // lstat failed too — terminal doesn't exist at all.\n  }\n\n  // Sub-case B: walk up to the nearest existing ancestor, then re-attach\n  // the suffix lexically.\n  let cursor = dirname(path);\n  let suffix = path.slice(cursor.length);\n  while (cursor !== dirname(cursor)) {\n    try {\n      const real = realpathSync(cursor);\n      // Reconstruct: ancestor's realpath + remaining (still-lexical) suffix\n      return resolve(real, `.${suffix}`);\n    } catch {\n      suffix = path.slice(dirname(cursor).length);\n      cursor = dirname(cursor);\n    }\n  }\n  // Reached filesystem root without finding any existing ancestor.\n  return undefined;\n}\n\nconst LOCK_FILES = new Set([\"pnpm-lock.yaml\", \"package-lock.json\", \"yarn.lock\", \"bun.lockb\"]);\n\n// T5.6 — top-level credential dot-dirs / dot-files. Matching against\n// the FIRST path segment (lowercase). Adding any entry here costs a\n// CHANGELOG note + an explicit case-fold test (entries are lowercased\n// at module load).\nconst SENSITIVE_FIRST_SEGMENTS = new Set([\n  \".ssh\",\n  \".aws\",\n  \".docker\",\n  \".kube\",\n  \".npmrc\",\n  \".netrc\",\n  \".pgpass\",\n]);\n\n// T5.6 — credential basenames blocked at ANY depth (lowercase). Catches\n// the developer-laptop case where an agent recurses into a subdir.\nconst SENSITIVE_BASENAMES = new Set([\n  \"id_rsa\",\n  \"id_ed25519\",\n  \"id_ecdsa\",\n  \"id_dsa\",\n  \"authorized_keys\",\n  \"known_hosts\",\n  \".npmrc\",\n  \".netrc\",\n  \".pgpass\",\n]);\n\n// T5.6 — extension suffixes blocked at ANY depth (lowercase). Covers\n// the entire `*.pem` / `*.key` private-material family.\nconst SENSITIVE_SUFFIXES = [\".pem\", \".key\", \".p12\", \".pfx\"];\n\n/**\n * Decide whether a project-relative path points to a known-sensitive file\n * that a coding agent must not read or write.\n *\n * Universal blocklist (works for any agent operating on a project tree):\n *\n *   - `.env`, `.env.<anything>` — except `.env.example` (template safe to read)\n *   - `.git/` — version control internals\n *   - `node_modules/` — dependency cache (changes don't belong to the user)\n *   - `.theo/` — TheoKit build artefacts / state\n *   - Lock files at any depth: `pnpm-lock.yaml`, `package-lock.json`,\n *     `yarn.lock`, `bun.lockb`\n *\n * Operates on path segments (forward-slash normalized). Cross-platform safe.\n *\n * Use together with `safePathJoin` + `assertNoSymlinkEscape`: the former two\n * defeat traversal, this one defeats reading a file that is lexically inside\n * the project but should not be agent-visible.\n *\n * @public\n */\nexport function isForbiddenPath(input: string): boolean {\n  // T5.6 — lowercase normalization defeats case-only bypass on\n  // case-insensitive filesystems (Windows/macOS-default) where `.ENV`\n  // and `.env` map to the same inode but a case-sensitive string\n  // check passes the former.\n  const normalized = input.replace(/\\\\/g, \"/\").replace(/^\\.\\//, \"\").toLowerCase();\n  if (normalized.length === 0) return false;\n\n  const segments = normalized.split(\"/\").filter((s) => s.length > 0);\n  if (segments.length === 0) return false;\n\n  if (isForbiddenFirstSegment(segments[0]!)) return true;\n  if (isForbiddenBasename(segments[segments.length - 1]!)) return true;\n  return false;\n}\n\nfunction isForbiddenFirstSegment(first: string): boolean {\n  // .env.example is explicitly allowlisted (template safe to read)\n  if (first === \".env.example\") return false;\n  if (first === \".env\") return true;\n  if (/^\\.env\\./.test(first)) return true;\n  if (first === \".git\" || first === \"node_modules\" || first === \".theo\") return true;\n  return SENSITIVE_FIRST_SEGMENTS.has(first);\n}\n\nfunction isForbiddenBasename(basename: string): boolean {\n  if (LOCK_FILES.has(basename)) return true;\n  if (SENSITIVE_BASENAMES.has(basename)) return true;\n  for (const suffix of SENSITIVE_SUFFIXES) {\n    if (basename.endsWith(suffix)) return true;\n  }\n  return false;\n}\n\nconst IDENTIFIER_PATTERN = /^[a-z0-9][a-z0-9\\-_]*$/i;\n\n/**\n * T1.4 — validate a relative artifact path string BEFORE it is used to look\n * up a fixture or to fetch from PaaS. Rejects every well-known traversal\n * vector at the boundary, throwing `PathTraversalError`.\n *\n * Vectors rejected:\n *  - classic `..` parent-directory traversal (any segment).\n *  - backslash separators (Windows-style `..\\\\windows`).\n *  - URL-encoded `%2e%2e` / `%2E%2E` (double-decoded traversal).\n *  - NUL byte injection (`\\x00`).\n *  - Windows drive letter prefix (`C:`, `D:\\\\...`).\n *  - Home-tilde expansion (`~/`, `~root/...`).\n *  - Absolute paths starting with `/`.\n *\n * Does NOT touch the filesystem — the call is shape-only. Live symlink\n * traversal protection happens via `assertNoSymlinkEscape` at the FS-resolve\n * boundary.\n *\n * @param input - Caller-supplied artifact path.\n * @throws `PathTraversalError` on any rejection.\n *\n * Semver-exempt: reachable via the `@theokit/sdk/internal/security` sub-path, which the package\n * declares in `exports` but does NOT cover with its semver contract.\n */\nexport function validateArtifactPath(input: string): void {\n  rejectKnownPrefixVectors(input);\n  const normalized = decodeAndNormalize(input);\n  rejectParentTraversal(input, normalized);\n}\n\nfunction rejectKnownPrefixVectors(input: string): void {\n  if (input.includes(\"\\x00\")) {\n    throw new PathTraversalError(input, \"<nul-byte>\");\n  }\n  if (input.startsWith(\"/\") || input.startsWith(\"~\")) {\n    throw new PathTraversalError(input, input);\n  }\n  if (/^[A-Za-z]:[\\\\/]?/.test(input)) {\n    throw new PathTraversalError(input, input);\n  }\n}\n\nfunction decodeAndNormalize(input: string): string {\n  // URL-encoded traversal — 2 passes catches `%252e%252e`.\n  // Malformed sequences (decodeURIComponent throws) are themselves a rejection.\n  let decoded = input;\n  for (let i = 0; i < 2; i += 1) {\n    try {\n      const next = decodeURIComponent(decoded);\n      if (next === decoded) break;\n      decoded = next;\n    } catch {\n      throw new PathTraversalError(input, \"<malformed-url-encoding>\");\n    }\n  }\n  // Normalize backslash to forward slash before segment-walking.\n  return decoded.replace(/\\\\/g, \"/\");\n}\n\nfunction rejectParentTraversal(input: string, normalized: string): void {\n  for (const segment of normalized.split(\"/\")) {\n    if (segment === \"..\" || segment === \"..%00\") {\n      throw new PathTraversalError(input, normalized);\n    }\n  }\n  // Defense in depth: literal `..` anywhere in the normalized string.\n  if (normalized.includes(\"..\")) {\n    throw new PathTraversalError(input, normalized);\n  }\n}\n\n/**\n * Validate that `input` is a safe path component (skill name, agent ID,\n * namespace, etc.) and return its lowercase form. Strict grammar\n * `^[a-z0-9][a-z0-9-_]*$` rejects path separators, dots, null bytes,\n * whitespace, unicode invisible chars, and any leading `-`/`_`.\n *\n * ONE error class leaves this function: `ConfigurationError` with code\n * `invalid_identifier`, for every rejection — length out of range, a path\n * separator, `..`, a space, a leading `-`, and a NUL / C0 control char / DEL\n * alike. A caller can branch on that code and know it has covered the whole\n * rejection surface.\n *\n * Before #368 the control-char branch threw `PathTraversalError` instead, which\n * made the error CLASS a function of the attacker's bytes; the message still names\n * the offending byte, which is the part that was worth keeping.\n *\n * @param input - User-supplied identifier candidate.\n * @param options.maxLen - Maximum allowed length (default 64).\n * @returns Lowercase form of `input`.\n * @throws `ConfigurationError` with code `invalid_identifier` on every rejection.\n */\nexport function sanitizeIdentifier(input: string, options?: { maxLen?: number }): string {\n  const maxLen = options?.maxLen ?? 64;\n  if (input.length === 0 || input.length > maxLen) {\n    throw new ConfigurationError(`Identifier length out of range (1-${maxLen}): \"${input}\"`, {\n      code: \"invalid_identifier\",\n    });\n  }\n  // T5.5 — explicit NUL / control char rejection ahead of the generic pattern check. The\n  // IDENTIFIER_PATTERN regex already excludes these (they are not in `[a-z0-9\\-_]`); naming the\n  // offending byte gives operators a precise diagnostic instead of the generic \"invalid characters\"\n  // message, which is what makes a prompt-injection trace legible (Rule 3).\n  //\n  // #368 — the diagnostic used to arrive as a `PathTraversalError`, because the branch reused\n  // `safePathJoin`'s thrower. That made the error CLASS a function of the attacker's bytes: a\n  // caller branching on the documented `invalid_identifier` rethrew for any input carrying a\n  // control char, so a rejection surfaced as a 500 and the 400/500 split became an oracle. The\n  // detection is shared; the error each contract documents is not.\n  const controlChar = firstControlCharLabel(input);\n  if (controlChar !== undefined) {\n    throw new ConfigurationError(`Identifier contains ${controlChar}: \"${input}\"`, {\n      code: \"invalid_identifier\",\n    });\n  }\n  if (!IDENTIFIER_PATTERN.test(input)) {\n    throw new ConfigurationError(`Identifier contains invalid characters: \"${input}\"`, {\n      code: \"invalid_identifier\",\n    });\n  }\n  return input.toLowerCase();\n}\n\n/**\n * Convert ANY opaque id (agent id, run id, conversation id, namespace, email,\n * arbitrary string) into a deterministic, filesystem-safe filename component.\n *\n * Unlike {@link sanitizeIdentifier} (which THROWS on non-conforming input),\n * this is a total function: it NEVER throws on a non-empty string. It returns\n * the lowercased id verbatim when it already matches the safe grammar\n * `^[a-z0-9][a-z0-9-_]*$` and fits `maxLen` (so UUIDs, hashes, and slugs stay\n * human-readable), otherwise a deterministic `h-<16 hex>` sha256 token\n * (collision-resistant and always a valid filename). The output charset is\n * always `[a-z0-9_-]`, safe as a literal path segment on every filesystem.\n *\n * @param id - any opaque identifier (must be a non-empty string)\n * @param options.maxLen - max length for the passthrough branch (default 128).\n *   Ids longer than this are hashed; the hash token itself is always short.\n * @throws ConfigurationError (code `invalid_filename_id`) only on empty input.\n *\n * @example\n *   safeFilenameForId(\"550e8400-e29b-41d4-a716-446655440000\") // passthrough\n *   safeFilenameForId(\"user@example.com\")                      // \"h-<16hex>\"\n *\n */\nexport function safeFilenameForId(id: string, options?: { maxLen?: number }): string {\n  if (id.length === 0) {\n    throw new ConfigurationError(\"Filename id must be a non-empty string\", {\n      code: \"invalid_filename_id\",\n    });\n  }\n  const maxLen = options?.maxLen ?? 128;\n  const lower = id.toLowerCase();\n  if (lower.length <= maxLen && IDENTIFIER_PATTERN.test(lower)) {\n    return lower;\n  }\n  return `h-${createHash(\"sha256\").update(id).digest(\"hex\").slice(0, 16)}`;\n}\n"]}

package/dist/{chunk-CASUEY42.cjs → chunk-VX4SQ2LY.cjs}

@@ -1,10 +1,10 @@
 'use strict';
 
-var chunkNLXOGBRJ_cjs = require('./chunk-NLXOGBRJ.cjs');
-var chunkNGESVVJN_cjs = require('./chunk-NGESVVJN.cjs');
+var chunkDKK5QY4C_cjs = require('./chunk-DKK5QY4C.cjs');
+var chunk3FFAEAUJ_cjs = require('./chunk-3FFAEAUJ.cjs');
 var chunkNINIJCHU_cjs = require('./chunk-NINIJCHU.cjs');
-var chunkK3FW2XZD_cjs = require('./chunk-K3FW2XZD.cjs');
-var chunkJTB5Q42C_cjs = require('./chunk-JTB5Q42C.cjs');
+var chunk4ZHTIJNE_cjs = require('./chunk-4ZHTIJNE.cjs');
+var chunkXL7Q7HB2_cjs = require('./chunk-XL7Q7HB2.cjs');
 var croner = require('croner');
 
 // src/internal/cron/run-job.ts
@@ -12,7 +12,7 @@ async function runCronJob(job) {
   if (job.workflow !== void 0) return job.workflow.run(job.inputData);
   if (job.agent !== void 0) return runWithEphemeralAgent(job.agent, requireMessage(job));
   if (job.agentId !== void 0) return runWithExistingAgent(job.agentId, requireMessage(job));
-  throw new chunkK3FW2XZD_cjs.ConfigurationError(
+  throw new chunk4ZHTIJNE_cjs.ConfigurationError(
     `Cron job ${job.id} has no target (agent, agentId, or workflow) \u2014 cannot run.`,
     { code: "cron_no_target" }
   );
@@ -22,7 +22,7 @@ function isAgentRun(outcome) {
 }
 function requireMessage(job) {
   if (job.message === void 0) {
-    throw new chunkK3FW2XZD_cjs.ConfigurationError(`Cron job ${job.id} is an agent target but has no message.`, {
+    throw new chunk4ZHTIJNE_cjs.ConfigurationError(`Cron job ${job.id} is an agent target but has no message.`, {
       code: "cron_missing_message"
     });
   }
@@ -31,7 +31,7 @@ function requireMessage(job) {
 async function runWithExistingAgent(agentId, message) {
   const info = await chunkNINIJCHU_cjs.getAgentFacade().get(agentId).catch(() => void 0);
   if (info === void 0) {
-    throw new chunkK3FW2XZD_cjs.UnknownAgentError(
+    throw new chunk4ZHTIJNE_cjs.UnknownAgentError(
       `Cron job references agentId "${agentId}" but no such agent is registered. The agent may have been disposed or the process restarted without persisting the agent registry.`,
       { code: "agent_not_registered" }
     );
@@ -49,7 +49,7 @@ async function fireCronJobAsTask(job) {
   const fireTs = Date.now();
   const taskId = `cron-${job.id}-${fireTs}`;
   try {
-    await chunkNGESVVJN_cjs.submit({
+    await chunk3FFAEAUJ_cjs.submit({
       kind: "cron",
       id: taskId,
       allowReservedPrefix: true,
@@ -187,13 +187,13 @@ var FIELD_RANGES = [
 ];
 function validateCronExpression(cron) {
   if (typeof cron !== "string" || cron.length === 0) {
-    throw new chunkK3FW2XZD_cjs.ConfigurationError("Invalid cron expression: empty", {
+    throw new chunk4ZHTIJNE_cjs.ConfigurationError("Invalid cron expression: empty", {
       code: "invalid_cron"
     });
   }
   if (cron.startsWith("@")) {
     if (!SHORTHANDS.has(cron)) {
-      throw new chunkK3FW2XZD_cjs.ConfigurationError(`Invalid cron expression: unknown shorthand ${cron}`, {
+      throw new chunk4ZHTIJNE_cjs.ConfigurationError(`Invalid cron expression: unknown shorthand ${cron}`, {
         code: "invalid_cron"
       });
     }
@@ -201,7 +201,7 @@ function validateCronExpression(cron) {
   }
   const fields = cron.trim().split(/\s+/);
   if (fields.length !== FIELD_RANGES.length) {
-    throw new chunkK3FW2XZD_cjs.ConfigurationError(
+    throw new chunk4ZHTIJNE_cjs.ConfigurationError(
       `Invalid cron expression: ${cron} (expected ${FIELD_RANGES.length} fields, got ${fields.length})`,
       { code: "invalid_cron" }
     );
@@ -209,7 +209,7 @@ function validateCronExpression(cron) {
   for (const [index, range] of FIELD_RANGES.entries()) {
     const field = fields[index];
     if (!isValidCronField(field, range)) {
-      throw new chunkK3FW2XZD_cjs.ConfigurationError(`Invalid cron expression: ${cron} (field ${index + 1})`, {
+      throw new chunk4ZHTIJNE_cjs.ConfigurationError(`Invalid cron expression: ${cron} (field ${index + 1})`, {
         code: "invalid_cron"
       });
     }
@@ -251,7 +251,7 @@ function validateTimezone(timezone) {
   try {
     new Intl.DateTimeFormat("en-US", { timeZone: timezone });
   } catch {
-    throw new chunkK3FW2XZD_cjs.ConfigurationError(`Invalid IANA timezone: ${timezone}`, {
+    throw new chunk4ZHTIJNE_cjs.ConfigurationError(`Invalid IANA timezone: ${timezone}`, {
       code: "invalid_timezone"
     });
   }
@@ -295,7 +295,7 @@ var Cron = class {
     const job = getJob(jobId);
     if (job === void 0) {
       return Promise.reject(
-        new chunkK3FW2XZD_cjs.UnknownAgentError(`Cron job ${jobId} not found`, { code: "unknown_cron_job" })
+        new chunk4ZHTIJNE_cjs.UnknownAgentError(`Cron job ${jobId} not found`, { code: "unknown_cron_job" })
       );
     }
     return Promise.resolve(job);
@@ -335,7 +335,7 @@ var Cron = class {
   static async run(jobId, _options = {}) {
     const job = getJob(jobId);
     if (job === void 0) {
-      throw new chunkK3FW2XZD_cjs.UnknownAgentError(`Cron job ${jobId} not found`, { code: "unknown_cron_job" });
+      throw new chunk4ZHTIJNE_cjs.UnknownAgentError(`Cron job ${jobId} not found`, { code: "unknown_cron_job" });
     }
     return runCronJob(job);
   }
@@ -373,11 +373,11 @@ async function createCronJob(options) {
   validateCronExpression(options.cron);
   const timezone = options.timezone ?? "UTC";
   validateTimezone(timezone);
-  chunkJTB5Q42C_cjs.resolveApiKey(options.apiKey);
+  chunkXL7Q7HB2_cjs.resolveApiKey(options.apiKey);
   const runtime = detectRuntime(options);
   const now = Date.now();
   const job = {
-    id: chunkNLXOGBRJ_cjs.generateCronId(),
+    id: chunkDKK5QY4C_cjs.generateCronId(),
     cron: options.cron,
     timezone,
     enabled: options.enabled ?? true,
@@ -400,25 +400,25 @@ function validateCronTarget(options) {
     (t) => t !== void 0
   ).length;
   if (targets > 1) {
-    throw new chunkK3FW2XZD_cjs.ConfigurationError(
+    throw new chunk4ZHTIJNE_cjs.ConfigurationError(
       "agent, agentId, and workflow are mutually exclusive \u2014 pass exactly one target.",
       { code: "cron_ambiguous_target" }
     );
   }
   if (targets === 0) {
-    throw new chunkK3FW2XZD_cjs.ConfigurationError(
+    throw new chunk4ZHTIJNE_cjs.ConfigurationError(
       "Cron job requires exactly one target: agent, agentId, or workflow.",
       { code: "cron_no_target" }
     );
   }
   if (options.workflow !== void 0 && options.message !== void 0) {
-    throw new chunkK3FW2XZD_cjs.ConfigurationError(
+    throw new chunk4ZHTIJNE_cjs.ConfigurationError(
       "A workflow cron target takes inputData, not a message \u2014 remove `message`.",
       { code: "cron_workflow_message" }
     );
   }
   if (options.workflow === void 0 && options.message === void 0) {
-    throw new chunkK3FW2XZD_cjs.ConfigurationError("An agent cron target requires a message.", {
+    throw new chunk4ZHTIJNE_cjs.ConfigurationError("An agent cron target requires a message.", {
       code: "cron_missing_message"
     });
   }
@@ -435,7 +435,7 @@ function detectRuntime(options) {
 async function updateJobStatus(jobId, enabled) {
   const existing = getJob(jobId);
   if (existing === void 0) {
-    throw new chunkK3FW2XZD_cjs.UnknownAgentError(`Cron job ${jobId} not found`, { code: "unknown_cron_job" });
+    throw new chunk4ZHTIJNE_cjs.UnknownAgentError(`Cron job ${jobId} not found`, { code: "unknown_cron_job" });
   }
   const updated = {
     ...existing,
@@ -454,5 +454,5 @@ async function updateJobStatus(jobId, enabled) {
 }
 
 exports.Cron = Cron;
-//# sourceMappingURL=chunk-CASUEY42.cjs.map
-//# sourceMappingURL=chunk-CASUEY42.cjs.map
+//# sourceMappingURL=chunk-VX4SQ2LY.cjs.map
+//# sourceMappingURL=chunk-VX4SQ2LY.cjs.map