@theokit/sdk 4.27.0 → 4.29.0

package/dist/server/auth/index.d.ts

@@ -1,15 +1,211 @@
+import { IncomingMessage, ServerResponse } from 'node:http';
+
 /**
- * @theokit/sdk/server/auth — public barrel
+ * @theokit/sdk/server/auth — typed error classes
  *
- * Per ADR D6 (sub-path export) — consumers import via `@theokit/sdk/server/auth`
- * NOT main `@theokit/sdk` barrel. Tree-shaking + allows breaking changes in
- * auth surface without affecting Agent runtime consumers.
+ * Plan T1.2 + v1.1 EC-1 (AuthCancelledError for OAuth provider error response RFC 6749 §4.1.2.1).
+ */
+/**
+ * Thrown at `defineAuth()` time when configuration is invalid
+ * (e.g., duplicate provider name, invalid email shape per EC-V1-12).
+ */
+declare class AuthConfigError extends Error {
+    readonly name = "AuthConfigError";
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+/**
+ * Thrown at `startSignIn(providerName, ...)` or `finishSignIn(providerName, ...)`
+ * when the named provider is not registered in `providers[]`.
+ */
+declare class AuthProviderNotFoundError extends Error {
+    readonly name = "AuthProviderNotFoundError";
+    readonly providerName: string;
+    constructor(providerName: string);
+}
+/**
+ * Thrown during OAuth callback handling for state mismatches, expired
+ * transactions, missing query params, or provider 4xx/5xx errors.
+ *
+ * Typed `code` field lets consumers branch on cause:
+ *   - 'oauth_transaction_expired' — cookie tx > 10min old (per ADR D5)
+ *   - 'oauth_state_mismatch' — query state ≠ cookie state (CSRF defense per RFC 6749 §10.12)
+ *   - 'oauth_provider_error' — non-access_denied error in callback URL
+ *   - 'oauth_token_exchange_failed' — provider rejected code-for-tokens swap
+ *   - 'oauth_userinfo_failed' — userinfo endpoint returned error
+ *   - 'oauth_missing_code_or_state' — required query params absent
+ */
+declare class AuthCallbackError extends Error {
+    readonly name: string;
+    readonly code: string;
+    constructor(code: string, message?: string);
+}
+/**
+ * Per v1.1 EC-1 MUST FIX — typed subclass of AuthCallbackError for the
+ * specific case where user declined consent at provider screen.
+ *
+ * OAuth 2.0 RFC 6749 §4.1.2.1: provider redirects with `?error=access_denied`.
+ * Apps can catch this distinctly from network/server errors to render
+ * "Login cancelled — try again" UX instead of opaque "callback failed".
+ */
+declare class AuthCancelledError extends AuthCallbackError {
+    readonly name: string;
+    readonly errorDescription?: string;
+    constructor(errorDescription?: string);
+}
+
+/**
+ * @theokit/sdk/server/auth — orchestrator types (Caminho C Hybrid per G11)
+ *
+ * Plan: g11-auth-architecture-implementation v1.4 (sha256 4d381020...)
+ * Blueprint: g11-auth-architecture-decision v1.1 (SHIPPABLE 97.9)
+ * AUTH-DELEGATION lock (theokit/CLAUDE.md:217-225) — these types are the
+ * orchestrator contract; concrete OAuth/email providers ship in opt-in
+ * @theokit/auth-* packages (adapters layer per ADR D11).
+ */
+
+/**
+ * SessionManager contract (matches theokit/packages/theo/src/server/auth/session.ts:49).
+ * Imported as type-only — runtime depends via peerDep `theokit@>=0.2.4`.
+ */
+interface SessionManager<TSession> {
+    getSession(req: IncomingMessage): Promise<TSession | null>;
+    createSession(res: ServerResponse, data: TSession): Promise<void>;
+    destroySession(res: ServerResponse): void;
+    rotateSession(req: IncomingMessage, res: ServerResponse): Promise<TSession | null>;
+}
+/**
+ * Per ADR D5 — OAuth transaction state stored in encrypted HttpOnly cookie
+ * (cookie-state pattern). Expires within 10 minutes per invariant.
+ */
+interface OAuthTransaction {
+    state: string;
+    pkceVerifier?: string;
+    returnTo?: string;
+    createdAt: number;
+    expiresAt: number;
+}
+/**
+ * Per ADR D9 — provider profile types are provider-specific (not unified).
+ * Each @theokit/auth-* package exports its own profile shape.
+ * Generic param TProfile lets consumers narrow via discriminated unions on providerName.
+ */
+interface AuthResult<TProfile, TName extends string = string> {
+    profile: TProfile;
+    providerName: TName;
+    rawTokens?: {
+        accessToken: string;
+        refreshToken?: string;
+        idToken?: string;
+        expiresAt?: number;
+    };
+}
+/**
+ * Provider contract — each @theokit/auth-* package implements this.
+ * Per blueprint Q5 + ADR D11 (adapters layer).
+ */
+interface AuthProvider<TProfile, TName extends string = string> {
+    name: TName;
+    createAuthorizationURL(tx: OAuthTransaction): URL | Promise<URL>;
+    handleCallback(req: IncomingMessage, tx: OAuthTransaction): Promise<AuthResult<TProfile, TName>>;
+}
+/**
+ * `defineAuth(opts)` configuration shape — Caminho C (Hybrid).
+ * `providers` optional: empty = Caminho A escape hatch (manual signIn only).
+ * `onSignIn` invoked after provider callback success; returns TSession to persist.
+ */
+interface DefineAuthOptions<TSession> {
+    session: SessionManager<TSession>;
+    providers?: AuthProvider<unknown, string>[];
+    onSignIn?: <TProfile>(args: {
+        profile: TProfile;
+        provider: string;
+    }) => Promise<TSession>;
+    onSignOut?: (session: TSession | null) => Promise<void> | void;
+}
+/**
+ * Returned by `defineAuth<TSession>(opts)` — 5-method orchestrator surface.
+ *
+ * - startSignIn: returns Response.redirect to provider authorization URL with state cookie
+ * - finishSignIn: handles provider callback; verifies state; calls onSignIn; rotates session ID
+ *   (OWASP A07:2021 per EC-10); creates session cookie; clears transaction cookie
+ * - signIn: Caminho A escape hatch — skip OAuth flow; directly persist session from external profile
+ * - signOut: destroys session cookie + invokes onSignOut callback
+ * - getSession: read-only passthrough to session.getSession
+ */
+interface AuthOrchestrator<TSession> {
+    startSignIn(providerName: string, req: IncomingMessage, opts?: {
+        returnTo?: string;
+    }): Promise<Response>;
+    finishSignIn(providerName: string, req: IncomingMessage, res: ServerResponse): Promise<{
+        session: TSession;
+        returnTo?: string;
+    }>;
+    signIn<TProfile>(profile: TProfile, providerName: string, req: IncomingMessage, res: ServerResponse): Promise<TSession>;
+    signOut(res: ServerResponse): void | Promise<void>;
+    getSession(req: IncomingMessage): Promise<TSession | null>;
+}
+
+/**
+ * @theokit/sdk/server/auth — encrypted OAuth transaction cookie store
+ *
+ * Per ADR D5 — cookie-state pattern (no Redis/db dependency in core).
+ *
+ * Stores OAuthTransaction (state + pkceVerifier + returnTo + expiry) in a
+ * single signed+encrypted HttpOnly cookie. Stateless, works in edge/serverless.
+ *
+ * Cookie name: `__Host-theo_oauth_tx` (T5.3 — RFC 6265bis prefix)
+ * Lifetime: 10 minutes (per D5 invariant)
+ * Encryption: AES-256-GCM via Node's webcrypto subtle API
+ *
+ * Note: this is a minimal in-package implementation. Production deployments
+ * may prefer using `theokit/server/auth/crypto`'s encrypt/decrypt helpers
+ * via the SessionManager's existing secret rotation chain. For T1.2 we keep
+ * it self-contained to avoid cross-package peer-dep complexity; T2+ may
+ * refactor to share SessionManager's encrypt path.
+ */
+
+/**
+ * T5.1 — Typed error thrown when an OAuth tx-cookie secret has < 32
+ * bytes of entropy. Surfaces the actual byte length so operators can
+ * diagnose mis-configured env vars without leaking the secret itself.
+ *
+ * @public
+ */
+declare class AuthSecretTooShortError extends Error {
+    readonly name = "AuthSecretTooShortError";
+    constructor(actualBytes: number);
+}
+
+/**
+ * @theokit/sdk/server/auth — defineAuth orchestrator runtime (Caminho C Hybrid)
+ *
+ * Plan T1.2 implementation per blueprint Q5 § Caminho C signatures.
+ * Composes existing primitives + the v1.1 EC-1/EC-2/EC-10 fixes.
+ */
+
+/** SE36 — `Auth.create` replaces `defineAuth` (ADR 0015). @public */
+declare class Auth {
+    private constructor();
+    static create<TSession>(opts: DefineAuthOptions<TSession>): AuthOrchestrator<TSession>;
+}
+
+/**
+ * @theokit/sdk/server/auth — same-origin returnTo validator
+ *
+ * Per v1.1 EC-2 MUST FIX — OWASP A01:2021 open-redirect mitigation.
+ *
+ * Without this check, attacker craft `/login?returnTo=https://evil.com` would
+ * cause post-login redirect to attacker domain with authenticated session cookie.
  *
- * T1.1 shipped types-only.
- * T1.2 adds runtime: defineAuth() + 4 typed error classes + validateReturnTo helper.
+ * Rules:
+ *   - undefined/empty returnTo → default '/'
+ *   - protocol-relative `//evil.com` → default '/' (URL parser would resolve to baseUrl protocol)
+ *   - absolute URL with origin ≠ baseUrl.origin → default '/' (cross-origin redirect)
+ *   - absolute URL with origin === baseUrl.origin → keep (same-origin allowed)
+ *   - relative path starting with '/' → keep (same-app navigation)
+ *   - relative path not starting with '/' → default '/' (defensive)
  */
-export { AuthCallbackError, AuthCancelledError, AuthConfigError, AuthProviderNotFoundError, } from "./errors.js";
-export { AuthSecretTooShortError } from "./oauth-transaction-store.js";
-export { Auth } from "./orchestrator.js";
-export type { AuthOrchestrator, AuthProvider, AuthResult, DefineAuthOptions, OAuthTransaction, SessionManager, } from "./types.js";
-export { validateReturnTo } from "./validate-return-to.js";
+declare function validateReturnTo(returnTo: string | undefined, baseUrl: URL): string;
+
+export { Auth, AuthCallbackError, AuthCancelledError, AuthConfigError, type AuthOrchestrator, type AuthProvider, AuthProviderNotFoundError, type AuthResult, AuthSecretTooShortError, type DefineAuthOptions, type OAuthTransaction, type SessionManager, validateReturnTo };

package/dist/server/errors-envelope.d.cts

@@ -1,3 +1,8 @@
+import { T as TheokitAgentError } from '../errors-BdL-buYn.cjs';
+export { M as MemoryAdapterError } from '../errors-BdL-buYn.cjs';
+import '../run-OJbGyweZ.cjs';
+import 'zod';
+
 /**
  * @theokit/sdk/server/errors-envelope — G5 T2.2 boundary translation.
  *
@@ -12,7 +17,7 @@
  * dependency on `theokit`. Consumer code that uses both packages gets the
  * same shape via duck-typing.
  */
-import { MemoryAdapterError, TheokitAgentError } from "../errors.js";
+
 /**
  * Canonical envelope code union for cross-layer SDK boundary. Subset of the
  * full `TheoErrorCode` (theokit/server) covering codes the SDK actually emits.
@@ -21,13 +26,13 @@ import { MemoryAdapterError, TheokitAgentError } from "../errors.js";
  *
  * @public
  */
-export type TheokitErrorCode = "UNAUTHORIZED" | "RATE_LIMITED" | "INTERNAL_SERVER_ERROR" | "SERVICE_UNAVAILABLE" | "GATEWAY_TIMEOUT" | "AGENT_RUN_ERROR" | "PROVIDER_KEY_MISSING" | "BUDGET_EXCEEDED" | "CREDENTIAL_POOL_EXHAUSTED";
+type TheokitErrorCode = "UNAUTHORIZED" | "RATE_LIMITED" | "INTERNAL_SERVER_ERROR" | "SERVICE_UNAVAILABLE" | "GATEWAY_TIMEOUT" | "AGENT_RUN_ERROR" | "PROVIDER_KEY_MISSING" | "BUDGET_EXCEEDED" | "CREDENTIAL_POOL_EXHAUSTED";
 /**
  * Envelope shape — structurally identical to theokit/server `TheoErrorEnvelope`.
  *
  * @public
  */
-export interface TheokitErrorEnvelope<TExt = unknown> {
+interface TheokitErrorEnvelope<TExt = unknown> {
     readonly code: TheokitErrorCode;
     readonly message: string;
     readonly cause?: unknown;
@@ -49,7 +54,7 @@ export interface TheokitErrorEnvelope<TExt = unknown> {
  *
  * @public
  */
-export declare function toEnvelope(value: unknown): TheokitErrorEnvelope;
+declare function toEnvelope(value: unknown): TheokitErrorEnvelope;
 /**
  * Hydrate an envelope back into the SDK class hierarchy. Use at the inbound
  * boundary (e.g., on a worker process receiving an envelope from the main
@@ -57,5 +62,6 @@ export declare function toEnvelope(value: unknown): TheokitErrorEnvelope;
  *
  * @public
  */
-export declare function fromEnvelope(env: TheokitErrorEnvelope): TheokitAgentError;
-export { MemoryAdapterError };
+declare function fromEnvelope(env: TheokitErrorEnvelope): TheokitAgentError;
+
+export { type TheokitErrorCode, type TheokitErrorEnvelope, fromEnvelope, toEnvelope };

package/dist/server/errors-envelope.d.ts

@@ -1,3 +1,8 @@
+import { T as TheokitAgentError } from '../errors-DHZtSNnj.js';
+export { M as MemoryAdapterError } from '../errors-DHZtSNnj.js';
+import '../run-OJbGyweZ.js';
+import 'zod';
+
 /**
  * @theokit/sdk/server/errors-envelope — G5 T2.2 boundary translation.
  *
@@ -12,7 +17,7 @@
  * dependency on `theokit`. Consumer code that uses both packages gets the
  * same shape via duck-typing.
  */
-import { MemoryAdapterError, TheokitAgentError } from "../errors.js";
+
 /**
  * Canonical envelope code union for cross-layer SDK boundary. Subset of the
  * full `TheoErrorCode` (theokit/server) covering codes the SDK actually emits.
@@ -21,13 +26,13 @@ import { MemoryAdapterError, TheokitAgentError } from "../errors.js";
  *
  * @public
  */
-export type TheokitErrorCode = "UNAUTHORIZED" | "RATE_LIMITED" | "INTERNAL_SERVER_ERROR" | "SERVICE_UNAVAILABLE" | "GATEWAY_TIMEOUT" | "AGENT_RUN_ERROR" | "PROVIDER_KEY_MISSING" | "BUDGET_EXCEEDED" | "CREDENTIAL_POOL_EXHAUSTED";
+type TheokitErrorCode = "UNAUTHORIZED" | "RATE_LIMITED" | "INTERNAL_SERVER_ERROR" | "SERVICE_UNAVAILABLE" | "GATEWAY_TIMEOUT" | "AGENT_RUN_ERROR" | "PROVIDER_KEY_MISSING" | "BUDGET_EXCEEDED" | "CREDENTIAL_POOL_EXHAUSTED";
 /**
  * Envelope shape — structurally identical to theokit/server `TheoErrorEnvelope`.
  *
  * @public
  */
-export interface TheokitErrorEnvelope<TExt = unknown> {
+interface TheokitErrorEnvelope<TExt = unknown> {
     readonly code: TheokitErrorCode;
     readonly message: string;
     readonly cause?: unknown;
@@ -49,7 +54,7 @@ export interface TheokitErrorEnvelope<TExt = unknown> {
  *
  * @public
  */
-export declare function toEnvelope(value: unknown): TheokitErrorEnvelope;
+declare function toEnvelope(value: unknown): TheokitErrorEnvelope;
 /**
  * Hydrate an envelope back into the SDK class hierarchy. Use at the inbound
  * boundary (e.g., on a worker process receiving an envelope from the main
@@ -57,5 +62,6 @@ export declare function toEnvelope(value: unknown): TheokitErrorEnvelope;
  *
  * @public
  */
-export declare function fromEnvelope(env: TheokitErrorEnvelope): TheokitAgentError;
-export { MemoryAdapterError };
+declare function fromEnvelope(env: TheokitErrorEnvelope): TheokitAgentError;
+
+export { type TheokitErrorCode, type TheokitErrorEnvelope, fromEnvelope, toEnvelope };

package/dist/skills.cjs

@@ -1,7 +1,8 @@
 'use strict';
 
-var chunkLSLPF6OI_cjs = require('./chunk-LSLPF6OI.cjs');
+var chunkDHLZIMP6_cjs = require('./chunk-DHLZIMP6.cjs');
 require('./chunk-KIO7QFIV.cjs');
+require('./chunk-LALRCFSN.cjs');
 require('./chunk-A44COQJJ.cjs');
 require('./chunk-BEURCLDV.cjs');
 
@@ -9,11 +10,11 @@ require('./chunk-BEURCLDV.cjs');
 
 Object.defineProperty(exports, "buildSkillsBlock", {
   enumerable: true,
-  get: function () { return chunkLSLPF6OI_cjs.buildSkillsBlock; }
+  get: function () { return chunkDHLZIMP6_cjs.buildSkillsBlock; }
 });
 Object.defineProperty(exports, "discoverSkills", {
   enumerable: true,
-  get: function () { return chunkLSLPF6OI_cjs.discoverSkills; }
+  get: function () { return chunkDHLZIMP6_cjs.discoverSkills; }
 });
 //# sourceMappingURL=skills.cjs.map
 //# sourceMappingURL=skills.cjs.map

package/dist/skills.js

@@ -1,5 +1,6 @@
-export { buildSkillsBlock, discoverSkills } from './chunk-AKSBP7OO.js';
+export { buildSkillsBlock, discoverSkills } from './chunk-5IB2UKSN.js';
 import './chunk-POQT2OIF.js';
+import './chunk-FKCC2MED.js';
 import './chunk-WLKFWQSJ.js';
 import './chunk-JTFYYKDT.js';
 //# sourceMappingURL=skills.js.map

package/dist/subagents-loader.cjs

@@ -0,0 +1,19 @@
+'use strict';
+
+var chunkRZQ6E5YZ_cjs = require('./chunk-RZQ6E5YZ.cjs');
+require('./chunk-LALRCFSN.cjs');
+require('./chunk-A44COQJJ.cjs');
+require('./chunk-BEURCLDV.cjs');
+
+// src/subagents-loader.ts
+async function discoverSubagents(cwd) {
+  return chunkRZQ6E5YZ_cjs.loadSubagents(cwd, true, void 0);
+}
+async function loadSubagentDefinition(name, cwd) {
+  return (await discoverSubagents(cwd))[name];
+}
+
+exports.discoverSubagents = discoverSubagents;
+exports.loadSubagentDefinition = loadSubagentDefinition;
+//# sourceMappingURL=subagents-loader.cjs.map
+//# sourceMappingURL=subagents-loader.cjs.map

package/dist/subagents-loader.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/subagents-loader.ts"],"names":["loadSubagents"],"mappings":";;;;;;;;AA4BA,eAAsB,kBAAkB,GAAA,EAAuD;AAC7F,EAAA,OAAOA,+BAAA,CAAc,GAAA,EAAK,IAAA,EAAM,MAAS,CAAA;AAC3C;AAQA,eAAsB,sBAAA,CACpB,MACA,GAAA,EACsC;AACtC,EAAA,OAAA,CAAQ,MAAM,iBAAA,CAAkB,GAAG,CAAA,EAAG,IAAI,CAAA;AAC5C","file":"subagents-loader.cjs","sourcesContent":["/**\n * M81 — `.theokit/agents` discovery, exposed so a consumer can read the on-disk subagent\n * definitions with one import instead of hand-rolling a second parser.\n *\n * ## Why this file exists\n *\n * `src/skills.ts` already exposed `discoverSkills` for the sibling domain. Subagents had the same\n * loader — `internal/runtime/skills/subagents-loader.ts` — with no public door. A consumer behind\n * the layer boundary (the agent-builder never imports `@theokit/sdk*` directly) could not reach it,\n * so re-implementing was the only legal option. It re-implemented, and then wrote a test whose only\n * job was to watch the two parsers for drift. That test is the cleanest possible evidence that the\n * duplication should not exist.\n *\n * ## What crosses is the PARSED config\n *\n * The return is `AgentDefinition` — already interpreted — never the `.md` text or the frontmatter\n * shape. Exporting the file format would freeze an internal detail as public API; exporting the\n * parsed value leaves the format free to change.\n */\n\nimport { loadSubagents } from \"./internal/runtime/skills/subagents-loader.js\";\nimport type { AgentDefinition } from \"./types/agent.js\";\n\n/**\n * Discover the subagents defined under `<cwd>/.theokit/agents/*.md`.\n *\n * An absent directory yields `{}` — a project without subagents is the common case, not an error.\n */\nexport async function discoverSubagents(cwd: string): Promise<Record<string, AgentDefinition>> {\n  return loadSubagents(cwd, true, undefined);\n}\n\n/**\n * Load ONE subagent definition by name, or `undefined` when it is not defined on disk.\n *\n * A thin selector over {@link discoverSubagents} rather than a second reader: one parser is the\n * whole point of this module.\n */\nexport async function loadSubagentDefinition(\n  name: string,\n  cwd: string,\n): Promise<AgentDefinition | undefined> {\n  return (await discoverSubagents(cwd))[name];\n}\n"]}

package/dist/subagents-loader.d.cts

@@ -0,0 +1,39 @@
+import { a as AgentDefinition } from './agent-CdjSCbYz.cjs';
+import './run-OJbGyweZ.cjs';
+import 'zod';
+
+/**
+ * M81 — `.theokit/agents` discovery, exposed so a consumer can read the on-disk subagent
+ * definitions with one import instead of hand-rolling a second parser.
+ *
+ * ## Why this file exists
+ *
+ * `src/skills.ts` already exposed `discoverSkills` for the sibling domain. Subagents had the same
+ * loader — `internal/runtime/skills/subagents-loader.ts` — with no public door. A consumer behind
+ * the layer boundary (the agent-builder never imports `@theokit/sdk*` directly) could not reach it,
+ * so re-implementing was the only legal option. It re-implemented, and then wrote a test whose only
+ * job was to watch the two parsers for drift. That test is the cleanest possible evidence that the
+ * duplication should not exist.
+ *
+ * ## What crosses is the PARSED config
+ *
+ * The return is `AgentDefinition` — already interpreted — never the `.md` text or the frontmatter
+ * shape. Exporting the file format would freeze an internal detail as public API; exporting the
+ * parsed value leaves the format free to change.
+ */
+
+/**
+ * Discover the subagents defined under `<cwd>/.theokit/agents/*.md`.
+ *
+ * An absent directory yields `{}` — a project without subagents is the common case, not an error.
+ */
+declare function discoverSubagents(cwd: string): Promise<Record<string, AgentDefinition>>;
+/**
+ * Load ONE subagent definition by name, or `undefined` when it is not defined on disk.
+ *
+ * A thin selector over {@link discoverSubagents} rather than a second reader: one parser is the
+ * whole point of this module.
+ */
+declare function loadSubagentDefinition(name: string, cwd: string): Promise<AgentDefinition | undefined>;
+
+export { discoverSubagents, loadSubagentDefinition };

package/dist/subagents-loader.d.ts

@@ -0,0 +1,39 @@
+import { a as AgentDefinition } from './agent-BZz4X8ZM.js';
+import './run-OJbGyweZ.js';
+import 'zod';
+
+/**
+ * M81 — `.theokit/agents` discovery, exposed so a consumer can read the on-disk subagent
+ * definitions with one import instead of hand-rolling a second parser.
+ *
+ * ## Why this file exists
+ *
+ * `src/skills.ts` already exposed `discoverSkills` for the sibling domain. Subagents had the same
+ * loader — `internal/runtime/skills/subagents-loader.ts` — with no public door. A consumer behind
+ * the layer boundary (the agent-builder never imports `@theokit/sdk*` directly) could not reach it,
+ * so re-implementing was the only legal option. It re-implemented, and then wrote a test whose only
+ * job was to watch the two parsers for drift. That test is the cleanest possible evidence that the
+ * duplication should not exist.
+ *
+ * ## What crosses is the PARSED config
+ *
+ * The return is `AgentDefinition` — already interpreted — never the `.md` text or the frontmatter
+ * shape. Exporting the file format would freeze an internal detail as public API; exporting the
+ * parsed value leaves the format free to change.
+ */
+
+/**
+ * Discover the subagents defined under `<cwd>/.theokit/agents/*.md`.
+ *
+ * An absent directory yields `{}` — a project without subagents is the common case, not an error.
+ */
+declare function discoverSubagents(cwd: string): Promise<Record<string, AgentDefinition>>;
+/**
+ * Load ONE subagent definition by name, or `undefined` when it is not defined on disk.
+ *
+ * A thin selector over {@link discoverSubagents} rather than a second reader: one parser is the
+ * whole point of this module.
+ */
+declare function loadSubagentDefinition(name: string, cwd: string): Promise<AgentDefinition | undefined>;
+
+export { discoverSubagents, loadSubagentDefinition };

package/dist/subagents-loader.js

@@ -0,0 +1,16 @@
+import { loadSubagents } from './chunk-BNIFFFH3.js';
+import './chunk-FKCC2MED.js';
+import './chunk-WLKFWQSJ.js';
+import './chunk-JTFYYKDT.js';
+
+// src/subagents-loader.ts
+async function discoverSubagents(cwd) {
+  return loadSubagents(cwd, true, void 0);
+}
+async function loadSubagentDefinition(name, cwd) {
+  return (await discoverSubagents(cwd))[name];
+}
+
+export { discoverSubagents, loadSubagentDefinition };
+//# sourceMappingURL=subagents-loader.js.map
+//# sourceMappingURL=subagents-loader.js.map

package/dist/subagents-loader.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/subagents-loader.ts"],"names":[],"mappings":";;;;;;AA4BA,eAAsB,kBAAkB,GAAA,EAAuD;AAC7F,EAAA,OAAO,aAAA,CAAc,GAAA,EAAK,IAAA,EAAM,MAAS,CAAA;AAC3C;AAQA,eAAsB,sBAAA,CACpB,MACA,GAAA,EACsC;AACtC,EAAA,OAAA,CAAQ,MAAM,iBAAA,CAAkB,GAAG,CAAA,EAAG,IAAI,CAAA;AAC5C","file":"subagents-loader.js","sourcesContent":["/**\n * M81 — `.theokit/agents` discovery, exposed so a consumer can read the on-disk subagent\n * definitions with one import instead of hand-rolling a second parser.\n *\n * ## Why this file exists\n *\n * `src/skills.ts` already exposed `discoverSkills` for the sibling domain. Subagents had the same\n * loader — `internal/runtime/skills/subagents-loader.ts` — with no public door. A consumer behind\n * the layer boundary (the agent-builder never imports `@theokit/sdk*` directly) could not reach it,\n * so re-implementing was the only legal option. It re-implemented, and then wrote a test whose only\n * job was to watch the two parsers for drift. That test is the cleanest possible evidence that the\n * duplication should not exist.\n *\n * ## What crosses is the PARSED config\n *\n * The return is `AgentDefinition` — already interpreted — never the `.md` text or the frontmatter\n * shape. Exporting the file format would freeze an internal detail as public API; exporting the\n * parsed value leaves the format free to change.\n */\n\nimport { loadSubagents } from \"./internal/runtime/skills/subagents-loader.js\";\nimport type { AgentDefinition } from \"./types/agent.js\";\n\n/**\n * Discover the subagents defined under `<cwd>/.theokit/agents/*.md`.\n *\n * An absent directory yields `{}` — a project without subagents is the common case, not an error.\n */\nexport async function discoverSubagents(cwd: string): Promise<Record<string, AgentDefinition>> {\n  return loadSubagents(cwd, true, undefined);\n}\n\n/**\n * Load ONE subagent definition by name, or `undefined` when it is not defined on disk.\n *\n * A thin selector over {@link discoverSubagents} rather than a second reader: one parser is the\n * whole point of this module.\n */\nexport async function loadSubagentDefinition(\n  name: string,\n  cwd: string,\n): Promise<AgentDefinition | undefined> {\n  return (await discoverSubagents(cwd))[name];\n}\n"]}

package/dist/types/goal-events.d.ts

@@ -125,6 +125,14 @@ export interface GoalOptions {
     judgeModel?: string;
     /** Override env for the judge auxiliary agent. Default `OPENROUTER_API_KEY` (EC-A). */
     judgeApiKey?: string;
+    /**
+     * M80 — o modelo do agente CONDUZIDO, base da derivação do judge quando `judgeModel` é omitido.
+     *
+     * Existe porque o default fixo (`openai/gpt-4o-mini`) só resolve em OpenRouter: com chave
+     * Anthropic dá 404, com bearer OAuth dá 401, e o goal queimava 3 turnos antes de falhar com razão
+     * enganosa. Um judge que roda no mesmo modelo do chat funciona onde o chat funciona.
+     */
+    agentModel?: string;
     /** Optional subgoals fed to the judge prompt. */
     subgoals?: string[];
     /**

package/dist/workflow.cjs

@@ -4,8 +4,8 @@ var chunkZ2OC3UIW_cjs = require('./chunk-Z2OC3UIW.cjs');
 var chunkBWT67BI4_cjs = require('./chunk-BWT67BI4.cjs');
 require('./chunk-PNVDQL5Y.cjs');
 require('./chunk-WJVHMTKB.cjs');
-require('./chunk-KIO7QFIV.cjs');
 require('./chunk-TIZ4TS5V.cjs');
+require('./chunk-KIO7QFIV.cjs');
 require('./chunk-A44COQJJ.cjs');
 require('./chunk-BEURCLDV.cjs');
 

package/dist/workflow.js

@@ -2,8 +2,8 @@ export { Workflow, WorkflowBuilder, WorkflowToolError, agentStep, cloneWorkflow,
 export { WorkflowAlreadyRunningError, WorkflowCompensateNotImplementedError, WorkflowDuplicateStepIdError, WorkflowInputError, WorkflowMaxIterationsExceededError, WorkflowNestedError, WorkflowNotSerializableError, WorkflowOutputError, WorkflowParallelError, WorkflowResumeStepNotFoundError, WorkflowSnapshotNotFoundError, WorkflowStateError, __resetSnapshotStoresForTests } from './chunk-UVNG67DG.js';
 import './chunk-CAH3G4IS.js';
 import './chunk-4VPXM6UU.js';
-import './chunk-POQT2OIF.js';
 import './chunk-S2BBRVQX.js';
+import './chunk-POQT2OIF.js';
 import './chunk-WLKFWQSJ.js';
 import './chunk-JTFYYKDT.js';
 //# sourceMappingURL=workflow.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theokit/sdk",
-  "version": "4.27.0",
+  "version": "4.29.0",
   "description": "TypeScript SDK for the Theo agent harness — same surface, local or cloud.",
   "license": "Apache-2.0",
   "homepage": "https://github.com/usetheodev/theokit-sdk#readme",
@@ -298,7 +298,17 @@
         "default": "./dist/interactive/index.cjs"
       }
     },
-    "./package.json": "./package.json"
+    "./package.json": "./package.json",
+    "./subagents-loader": {
+      "import": {
+        "types": "./dist/subagents-loader.d.ts",
+        "default": "./dist/subagents-loader.js"
+      },
+      "require": {
+        "types": "./dist/subagents-loader.d.cts",
+        "default": "./dist/subagents-loader.cjs"
+      }
+    }
   },
   "files": [
     "dist",