@theokit/sdk 4.43.0 → 4.44.0

package/dist/index.d.cts

@@ -1835,6 +1835,71 @@ declare class PermissionPlugin {
     static create(engine: PermissionEngine, opts?: PermissionPluginOptions): Plugin;
 }
 
+/**
+ * Load a project's `.env` without letting it move the credential store or switch off a trust
+ * decision.
+ *
+ * `process.loadEnvFile()` reads the PROJECT's `.env` into `process.env`. For a provider key that is
+ * exactly right and is the documented way to configure a scaffolded product. For the handful of
+ * variables that decide WHERE credentials live and WHAT is trusted it is a hole: a cloned
+ * repository is untrusted input, and a `.env` inside it is untrusted input the runtime is about to
+ * treat as configuration.
+ *
+ * Concretely, without this guard a repository shipping
+ *
+ * ```
+ * THEOKIT_AUTH_HOME=/tmp/attacker-store
+ * ```
+ *
+ * redirects the credential store the moment the product starts in that directory — before any
+ * trust prompt, because locating the store is what happens first.
+ *
+ * ## Why it lives here
+ *
+ * The scaffolding template (`create-theokit`, TUI surface) calls `process.loadEnvFile()` with no
+ * guard, so every product generated from it starts exposed. One consumer found this and fixed it in
+ * ~30 lines of its own. A defence each consumer has to rediscover is a defence most will not have,
+ * and this one is invisible when missing: nothing fails, the store simply moves.
+ *
+ * ## Why the set is named
+ *
+ * A convention — "anything ending in `_HOME`", "anything with TRUST in it" — silently changes
+ * meaning as variables are added, in the direction of accidentally sovereign or accidentally not.
+ * The list is explicit so that making a variable sovereign is a deliberate act, and so a reader can
+ * see the security boundary without grepping for it.
+ *
+ * @public
+ */
+/**
+ * Variables a project-scoped source may never set. Each either locates the credential store, names
+ * the config directory that is read as configuration, or carries a trust decision.
+ *
+ * `THEOKIT_API_KEY` is deliberately ABSENT. A project supplying its own provider key through `.env`
+ * is the documented, intended path — treating it as sovereign would break every scaffolded product
+ * to defend nothing, since a key the project supplies is a key the project already has.
+ *
+ * @public
+ */
+declare const SOVEREIGN_ENV_KEYS: readonly ["THEOKIT_HOME", "THEOKIT_AUTH_HOME", "THEOKIT_DIR_NAME", "THEOKIT_TRUSTED_PROVIDERS", "THEOKIT_REDACT_SECRETS", "THEOKIT_OAUTH_TX_SALT"];
+/** @public */
+type SovereignEnvKey = (typeof SOVEREIGN_ENV_KEYS)[number];
+/** The mutable shape of `process.env`, narrowed so a caller can pass a plain object in tests. */
+type MutableEnv = Record<string, string | undefined>;
+/**
+ * Read the project's `.env` into `env`, then restore every {@link SOVEREIGN_ENV_KEYS} entry to the
+ * value it had BEFORE the load — including restoring it to absent.
+ *
+ * Capture-then-restore rather than filtering the file: `process.loadEnvFile` offers no hook between
+ * parsing and assignment, and reimplementing dotenv parsing to filter it would be a second parser
+ * to keep in step with Node's. Restoring afterwards needs no parser and cannot disagree with one.
+ *
+ * @param env the environment to mutate. Defaults to `process.env`.
+ * @param load performs the load. Defaults to `process.loadEnvFile` when the runtime has it, and to
+ *   `undefined` when it does not — in which case this is a no-op rather than a startup crash.
+ * @public
+ */
+declare function loadProjectEnv(env?: MutableEnv, load?: (() => void) | undefined): void;
+
 /** The internal JSON-Schema shape the synthetic `output` tool consumes. */
 type NormalizedJsonSchema = Record<string, unknown>;
 /**
@@ -2510,4 +2575,4 @@ declare function toShareGptTrajectory(result: BatchResult, options?: {
     model?: string;
 }): ShareGptTrajectory | null;
 
-export { Agent, AgentBuilder, AgentDefinition, AgentDescription, AgentFactory, AgentOperationOptions, AgentOptions, type AgentPromptResult, type AgentRegistryOptions, type BatchItem, type BatchOptions, type BatchProgress, type BatchResult, Budget, BudgetHandle, BudgetOptions, BudgetSnapshot, BudgetTracker, CloudOptions, ContextSettings, type CounterBudgetTrackerOptions, CustomTool, type DeepPartial, type DefineProviderOptions, type DefineToolSpec, type DiagnosticsSink, type DreamingSweepOptions, type DreamingSweepResult, ErrorMetadata, EventBus, type EvictReason, GOAL_CONTINUATION_MARKER, GenerateObjectError, type GenerateObjectOptions, type GenerateObjectResult, GetAgentOptions, GetRunOptions, GoalEvent, type GoalLoopAgent, GoalOptions, GoalResult, InlineSkill, JobQueue, type JobQueueOptions, JudgeCredentialError, JudgeResult, ListAgentsOptions, ListResult, ListRunsOptions, LiveAgentRegistry, LocalOptions, McpServerConfig, Memory, MemoryId, MemoryProvider, MemorySettings, type MigrateOptions, type MigrateResult, type ModelListItem, type ModelParameterDefinition, ModelSelection, type ModelVariant, NoopMemoryProvider, type NormalizedJsonSchema, PermissionEngine, type PermissionGate, type PermissionGateContext, type PermissionGateDecision, PermissionMode, PermissionPlugin, type PermissionPluginOptions, Plugin, PluginsSettings, PreToolCallDecision, Processor, Provider, ProviderProfile, ProviderRoutingSettings, Run, RunEventSink, RunResult, SDKAgent, SDKAgentInfo, SDKMessage, type SDKModel, SDKProvider, type SDKRepository, type SDKUser, Security, type SessionMessage, type SessionMessagePart, type SessionScope, type ShareGptMessage, type ShareGptTrajectory, SkillReadTool, SkillsSettings, Squad, type SquadOptions, type SquadRun, StreamObjectError, type StreamObjectEvent, type StreamObjectOptions, SystemPromptResolver, TASK_RESERVED_PREFIXES, Task, type TaskCancelResult, type TaskConfigureOptions, type TaskEvent, type TaskFilter, type TaskHandle, type TaskKind, type TaskState, type TaskStoreOptions, type TaskSubmitOptions, type TaskWorkContext, type TaskWorkFn, Theokit, TheokitAgentError, type TheokitRequestOptions, TokenLimiter, type TokenLimiterOptions, Tool, ToolError, ToolResultContentBlock, UnicodeNormalizer, type UnicodeNormalizerOptions, UsageAccumulator, chargeAndCheckThresholds, computeCost, createCounterBudgetTracker, estimateTokens, extractRawId, getPricingEntry, inferApiMode, isValidTaskId, migrateSqliteToLance, mkMemoryId, normalizeSchema, normalizeUsage, preflightCheck, runGoalLoop, scopedConversationId, sessionScopePrefix, setDiagnosticsSink, toShareGptTrajectory, withCwdMutex };
+export { Agent, AgentBuilder, AgentDefinition, AgentDescription, AgentFactory, AgentOperationOptions, AgentOptions, type AgentPromptResult, type AgentRegistryOptions, type BatchItem, type BatchOptions, type BatchProgress, type BatchResult, Budget, BudgetHandle, BudgetOptions, BudgetSnapshot, BudgetTracker, CloudOptions, ContextSettings, type CounterBudgetTrackerOptions, CustomTool, type DeepPartial, type DefineProviderOptions, type DefineToolSpec, type DiagnosticsSink, type DreamingSweepOptions, type DreamingSweepResult, ErrorMetadata, EventBus, type EvictReason, GOAL_CONTINUATION_MARKER, GenerateObjectError, type GenerateObjectOptions, type GenerateObjectResult, GetAgentOptions, GetRunOptions, GoalEvent, type GoalLoopAgent, GoalOptions, GoalResult, InlineSkill, JobQueue, type JobQueueOptions, JudgeCredentialError, JudgeResult, ListAgentsOptions, ListResult, ListRunsOptions, LiveAgentRegistry, LocalOptions, McpServerConfig, Memory, MemoryId, MemoryProvider, MemorySettings, type MigrateOptions, type MigrateResult, type ModelListItem, type ModelParameterDefinition, ModelSelection, type ModelVariant, NoopMemoryProvider, type NormalizedJsonSchema, PermissionEngine, type PermissionGate, type PermissionGateContext, type PermissionGateDecision, PermissionMode, PermissionPlugin, type PermissionPluginOptions, Plugin, PluginsSettings, PreToolCallDecision, Processor, Provider, ProviderProfile, ProviderRoutingSettings, Run, RunEventSink, RunResult, SDKAgent, SDKAgentInfo, SDKMessage, type SDKModel, SDKProvider, type SDKRepository, type SDKUser, SOVEREIGN_ENV_KEYS, Security, type SessionMessage, type SessionMessagePart, type SessionScope, type ShareGptMessage, type ShareGptTrajectory, SkillReadTool, SkillsSettings, type SovereignEnvKey, Squad, type SquadOptions, type SquadRun, StreamObjectError, type StreamObjectEvent, type StreamObjectOptions, SystemPromptResolver, TASK_RESERVED_PREFIXES, Task, type TaskCancelResult, type TaskConfigureOptions, type TaskEvent, type TaskFilter, type TaskHandle, type TaskKind, type TaskState, type TaskStoreOptions, type TaskSubmitOptions, type TaskWorkContext, type TaskWorkFn, Theokit, TheokitAgentError, type TheokitRequestOptions, TokenLimiter, type TokenLimiterOptions, Tool, ToolError, ToolResultContentBlock, UnicodeNormalizer, type UnicodeNormalizerOptions, UsageAccumulator, chargeAndCheckThresholds, computeCost, createCounterBudgetTracker, estimateTokens, extractRawId, getPricingEntry, inferApiMode, isValidTaskId, loadProjectEnv, migrateSqliteToLance, mkMemoryId, normalizeSchema, normalizeUsage, preflightCheck, runGoalLoop, scopedConversationId, sessionScopePrefix, setDiagnosticsSink, toShareGptTrajectory, withCwdMutex };

package/dist/index.d.ts

@@ -1835,6 +1835,71 @@ declare class PermissionPlugin {
     static create(engine: PermissionEngine, opts?: PermissionPluginOptions): Plugin;
 }
 
+/**
+ * Load a project's `.env` without letting it move the credential store or switch off a trust
+ * decision.
+ *
+ * `process.loadEnvFile()` reads the PROJECT's `.env` into `process.env`. For a provider key that is
+ * exactly right and is the documented way to configure a scaffolded product. For the handful of
+ * variables that decide WHERE credentials live and WHAT is trusted it is a hole: a cloned
+ * repository is untrusted input, and a `.env` inside it is untrusted input the runtime is about to
+ * treat as configuration.
+ *
+ * Concretely, without this guard a repository shipping
+ *
+ * ```
+ * THEOKIT_AUTH_HOME=/tmp/attacker-store
+ * ```
+ *
+ * redirects the credential store the moment the product starts in that directory — before any
+ * trust prompt, because locating the store is what happens first.
+ *
+ * ## Why it lives here
+ *
+ * The scaffolding template (`create-theokit`, TUI surface) calls `process.loadEnvFile()` with no
+ * guard, so every product generated from it starts exposed. One consumer found this and fixed it in
+ * ~30 lines of its own. A defence each consumer has to rediscover is a defence most will not have,
+ * and this one is invisible when missing: nothing fails, the store simply moves.
+ *
+ * ## Why the set is named
+ *
+ * A convention — "anything ending in `_HOME`", "anything with TRUST in it" — silently changes
+ * meaning as variables are added, in the direction of accidentally sovereign or accidentally not.
+ * The list is explicit so that making a variable sovereign is a deliberate act, and so a reader can
+ * see the security boundary without grepping for it.
+ *
+ * @public
+ */
+/**
+ * Variables a project-scoped source may never set. Each either locates the credential store, names
+ * the config directory that is read as configuration, or carries a trust decision.
+ *
+ * `THEOKIT_API_KEY` is deliberately ABSENT. A project supplying its own provider key through `.env`
+ * is the documented, intended path — treating it as sovereign would break every scaffolded product
+ * to defend nothing, since a key the project supplies is a key the project already has.
+ *
+ * @public
+ */
+declare const SOVEREIGN_ENV_KEYS: readonly ["THEOKIT_HOME", "THEOKIT_AUTH_HOME", "THEOKIT_DIR_NAME", "THEOKIT_TRUSTED_PROVIDERS", "THEOKIT_REDACT_SECRETS", "THEOKIT_OAUTH_TX_SALT"];
+/** @public */
+type SovereignEnvKey = (typeof SOVEREIGN_ENV_KEYS)[number];
+/** The mutable shape of `process.env`, narrowed so a caller can pass a plain object in tests. */
+type MutableEnv = Record<string, string | undefined>;
+/**
+ * Read the project's `.env` into `env`, then restore every {@link SOVEREIGN_ENV_KEYS} entry to the
+ * value it had BEFORE the load — including restoring it to absent.
+ *
+ * Capture-then-restore rather than filtering the file: `process.loadEnvFile` offers no hook between
+ * parsing and assignment, and reimplementing dotenv parsing to filter it would be a second parser
+ * to keep in step with Node's. Restoring afterwards needs no parser and cannot disagree with one.
+ *
+ * @param env the environment to mutate. Defaults to `process.env`.
+ * @param load performs the load. Defaults to `process.loadEnvFile` when the runtime has it, and to
+ *   `undefined` when it does not — in which case this is a no-op rather than a startup crash.
+ * @public
+ */
+declare function loadProjectEnv(env?: MutableEnv, load?: (() => void) | undefined): void;
+
 /** The internal JSON-Schema shape the synthetic `output` tool consumes. */
 type NormalizedJsonSchema = Record<string, unknown>;
 /**
@@ -2510,4 +2575,4 @@ declare function toShareGptTrajectory(result: BatchResult, options?: {
     model?: string;
 }): ShareGptTrajectory | null;
 
-export { Agent, AgentBuilder, AgentDefinition, AgentDescription, AgentFactory, AgentOperationOptions, AgentOptions, type AgentPromptResult, type AgentRegistryOptions, type BatchItem, type BatchOptions, type BatchProgress, type BatchResult, Budget, BudgetHandle, BudgetOptions, BudgetSnapshot, BudgetTracker, CloudOptions, ContextSettings, type CounterBudgetTrackerOptions, CustomTool, type DeepPartial, type DefineProviderOptions, type DefineToolSpec, type DiagnosticsSink, type DreamingSweepOptions, type DreamingSweepResult, ErrorMetadata, EventBus, type EvictReason, GOAL_CONTINUATION_MARKER, GenerateObjectError, type GenerateObjectOptions, type GenerateObjectResult, GetAgentOptions, GetRunOptions, GoalEvent, type GoalLoopAgent, GoalOptions, GoalResult, InlineSkill, JobQueue, type JobQueueOptions, JudgeCredentialError, JudgeResult, ListAgentsOptions, ListResult, ListRunsOptions, LiveAgentRegistry, LocalOptions, McpServerConfig, Memory, MemoryId, MemoryProvider, MemorySettings, type MigrateOptions, type MigrateResult, type ModelListItem, type ModelParameterDefinition, ModelSelection, type ModelVariant, NoopMemoryProvider, type NormalizedJsonSchema, PermissionEngine, type PermissionGate, type PermissionGateContext, type PermissionGateDecision, PermissionMode, PermissionPlugin, type PermissionPluginOptions, Plugin, PluginsSettings, PreToolCallDecision, Processor, Provider, ProviderProfile, ProviderRoutingSettings, Run, RunEventSink, RunResult, SDKAgent, SDKAgentInfo, SDKMessage, type SDKModel, SDKProvider, type SDKRepository, type SDKUser, Security, type SessionMessage, type SessionMessagePart, type SessionScope, type ShareGptMessage, type ShareGptTrajectory, SkillReadTool, SkillsSettings, Squad, type SquadOptions, type SquadRun, StreamObjectError, type StreamObjectEvent, type StreamObjectOptions, SystemPromptResolver, TASK_RESERVED_PREFIXES, Task, type TaskCancelResult, type TaskConfigureOptions, type TaskEvent, type TaskFilter, type TaskHandle, type TaskKind, type TaskState, type TaskStoreOptions, type TaskSubmitOptions, type TaskWorkContext, type TaskWorkFn, Theokit, TheokitAgentError, type TheokitRequestOptions, TokenLimiter, type TokenLimiterOptions, Tool, ToolError, ToolResultContentBlock, UnicodeNormalizer, type UnicodeNormalizerOptions, UsageAccumulator, chargeAndCheckThresholds, computeCost, createCounterBudgetTracker, estimateTokens, extractRawId, getPricingEntry, inferApiMode, isValidTaskId, migrateSqliteToLance, mkMemoryId, normalizeSchema, normalizeUsage, preflightCheck, runGoalLoop, scopedConversationId, sessionScopePrefix, setDiagnosticsSink, toShareGptTrajectory, withCwdMutex };
+export { Agent, AgentBuilder, AgentDefinition, AgentDescription, AgentFactory, AgentOperationOptions, AgentOptions, type AgentPromptResult, type AgentRegistryOptions, type BatchItem, type BatchOptions, type BatchProgress, type BatchResult, Budget, BudgetHandle, BudgetOptions, BudgetSnapshot, BudgetTracker, CloudOptions, ContextSettings, type CounterBudgetTrackerOptions, CustomTool, type DeepPartial, type DefineProviderOptions, type DefineToolSpec, type DiagnosticsSink, type DreamingSweepOptions, type DreamingSweepResult, ErrorMetadata, EventBus, type EvictReason, GOAL_CONTINUATION_MARKER, GenerateObjectError, type GenerateObjectOptions, type GenerateObjectResult, GetAgentOptions, GetRunOptions, GoalEvent, type GoalLoopAgent, GoalOptions, GoalResult, InlineSkill, JobQueue, type JobQueueOptions, JudgeCredentialError, JudgeResult, ListAgentsOptions, ListResult, ListRunsOptions, LiveAgentRegistry, LocalOptions, McpServerConfig, Memory, MemoryId, MemoryProvider, MemorySettings, type MigrateOptions, type MigrateResult, type ModelListItem, type ModelParameterDefinition, ModelSelection, type ModelVariant, NoopMemoryProvider, type NormalizedJsonSchema, PermissionEngine, type PermissionGate, type PermissionGateContext, type PermissionGateDecision, PermissionMode, PermissionPlugin, type PermissionPluginOptions, Plugin, PluginsSettings, PreToolCallDecision, Processor, Provider, ProviderProfile, ProviderRoutingSettings, Run, RunEventSink, RunResult, SDKAgent, SDKAgentInfo, SDKMessage, type SDKModel, SDKProvider, type SDKRepository, type SDKUser, SOVEREIGN_ENV_KEYS, Security, type SessionMessage, type SessionMessagePart, type SessionScope, type ShareGptMessage, type ShareGptTrajectory, SkillReadTool, SkillsSettings, type SovereignEnvKey, Squad, type SquadOptions, type SquadRun, StreamObjectError, type StreamObjectEvent, type StreamObjectOptions, SystemPromptResolver, TASK_RESERVED_PREFIXES, Task, type TaskCancelResult, type TaskConfigureOptions, type TaskEvent, type TaskFilter, type TaskHandle, type TaskKind, type TaskState, type TaskStoreOptions, type TaskSubmitOptions, type TaskWorkContext, type TaskWorkFn, Theokit, TheokitAgentError, type TheokitRequestOptions, TokenLimiter, type TokenLimiterOptions, Tool, ToolError, ToolResultContentBlock, UnicodeNormalizer, type UnicodeNormalizerOptions, UsageAccumulator, chargeAndCheckThresholds, computeCost, createCounterBudgetTracker, estimateTokens, extractRawId, getPricingEntry, inferApiMode, isValidTaskId, loadProjectEnv, migrateSqliteToLance, mkMemoryId, normalizeSchema, normalizeUsage, preflightCheck, runGoalLoop, scopedConversationId, sessionScopePrefix, setDiagnosticsSink, toShareGptTrajectory, withCwdMutex };

package/dist/index.js

@@ -1494,6 +1494,39 @@ var PermissionPlugin = class {
   }
 };
 
+// src/project-env.ts
+var SOVEREIGN_ENV_KEYS = [
+  /** Locates the SDK home — sessions, and the credential store beneath it. */
+  "THEOKIT_HOME",
+  /** Locates the credential store explicitly, independently of `THEOKIT_HOME`. */
+  "THEOKIT_AUTH_HOME",
+  /** Names the project config directory, so it decides which files are READ as configuration. */
+  "THEOKIT_DIR_NAME",
+  /** A trust decision: which providers are honoured without further checks. */
+  "THEOKIT_TRUSTED_PROVIDERS",
+  /** Turning redaction off from a repository's `.env` would put secrets into logs. */
+  "THEOKIT_REDACT_SECRETS",
+  /** Cryptographic material for the OAuth transaction cookie. */
+  "THEOKIT_OAUTH_TX_SALT"
+];
+function loadProjectEnv(env = process.env, load = typeof process.loadEnvFile === "function" ? () => {
+  process.loadEnvFile();
+} : void 0) {
+  if (load === void 0) return;
+  const sovereign = new Map(
+    SOVEREIGN_ENV_KEYS.map((key) => [key, env[key]])
+  );
+  try {
+    load();
+  } catch {
+    return;
+  }
+  for (const [key, original] of sovereign) {
+    if (original === void 0) delete env[key];
+    else env[key] = original;
+  }
+}
+
 // src/schema-normalizer.ts
 function isJsonSchemaObject(s) {
   if (typeof s !== "object" || s === null) return false;
@@ -2089,6 +2122,6 @@ function safeStringify(v) {
   }
 }
 
-export { AgentFactory, Budget, EventBus, JobQueue, Memory, NoopMemoryProvider, PermissionEngine, PermissionPlugin, Plugin, Provider, Security, Skill, SkillReadTool, Squad, Task, Theokit, TokenLimiter, UnicodeNormalizer, applyMode, chargeAndCheckThresholds, createCounterBudgetTracker, estimateTokens, extractRawId, inferApiMode, migrateSqliteToLance2 as migrateSqliteToLance, mkMemoryId, normalizeSchema, normalizeUsage, preflightCheck, runGoalLoop, scopedConversationId, sessionScopePrefix, toShareGptTrajectory };
+export { AgentFactory, Budget, EventBus, JobQueue, Memory, NoopMemoryProvider, PermissionEngine, PermissionPlugin, Plugin, Provider, SOVEREIGN_ENV_KEYS, Security, Skill, SkillReadTool, Squad, Task, Theokit, TokenLimiter, UnicodeNormalizer, applyMode, chargeAndCheckThresholds, createCounterBudgetTracker, estimateTokens, extractRawId, inferApiMode, loadProjectEnv, migrateSqliteToLance2 as migrateSqliteToLance, mkMemoryId, normalizeSchema, normalizeUsage, preflightCheck, runGoalLoop, scopedConversationId, sessionScopePrefix, toShareGptTrajectory };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map