@kodax-ai/kodax 0.7.41 → 0.7.42

package/dist/sdk-session.d.ts

@@ -0,0 +1,164 @@
+import { S as SessionData } from './types-chunks/session-storage.d-Cci897iM.js';
+import './types-chunks/types.d-mM8vqvhT.js';
+import './types-chunks/types.d-B1uGoVTE.js';
+
+/**
+ * FEATURE_173 Part B (v0.7.42) — Session Management Public SDK.
+ *
+ * Thin facades over FileSessionStorage + discoverInstances. All methods
+ * NEVER throw — missing sessions return null, blocked operations return
+ * an error envelope, missing directories return empty arrays / no-op
+ * watchers.
+ *
+ * The `@kodax-ai/kodax/session` SDK subpath re-exports this module.
+ */
+
+interface SessionSummary {
+    readonly id: string;
+    readonly title: string;
+    readonly msgCount: number;
+    readonly createdAt?: string;
+    readonly runtimeInfo?: {
+        workspaceRoot?: string;
+        gitRoot?: string;
+    };
+}
+interface ListSessionsOptions {
+    /**
+     * Alias for gitRoot; backwards-compat with KodaX Space terminology.
+     * When provided, list() is scoped to sessions from this project root.
+     */
+    readonly projectRoot?: string;
+    /**
+     * Which session scopes to include.
+     * - 'user' (default): only user-initiated sessions.
+     * - 'managed-task-worker': only managed-task worker sessions.
+     * - 'all': no scope filter.
+     */
+    readonly scope?: 'user' | 'managed-task-worker' | 'all';
+    /**
+     * Whether to include archived sessions (filename starts with `archived-`).
+     * Default false — no archived sessions exist today; reserved for future use.
+     */
+    readonly includeArchived?: boolean;
+    /** Maximum number of sessions to return. Default 50. */
+    readonly limit?: number;
+    /**
+     * ISO date string — return only sessions whose createdAt is before this
+     * timestamp. Applied after list + scope filtering.
+     */
+    readonly before?: string;
+}
+type WatchSessionsCallback = (event: {
+    kind: 'change' | 'add' | 'remove';
+    sessionId: string;
+}) => void;
+interface SessionManager {
+    listSessions: typeof listSessions;
+    loadSession: typeof loadSession;
+    forkSession: typeof forkSession;
+    rewindSession: typeof rewindSession;
+    setActiveEntry: typeof setActiveEntry;
+    deleteSession: typeof deleteSession;
+    listRunningSessions: typeof listRunningSessions;
+    watchSessions: typeof watchSessions;
+}
+/**
+ * List sessions, optionally filtered by scope, limit, and date.
+ * NEVER throws. Returns [] when the sessions directory is empty or missing.
+ */
+declare function listSessions(opts?: ListSessionsOptions): Promise<SessionSummary[]>;
+/**
+ * Load full session data by ID.
+ * Returns null for a missing session. NEVER throws.
+ */
+declare function loadSession(id: string): Promise<SessionData | null>;
+/**
+ * Fork a session at an optional selector.
+ * Returns null for a missing session. NEVER throws.
+ */
+declare function forkSession(id: string, opts?: {
+    selector?: string;
+    sessionId?: string;
+    title?: string;
+}): Promise<{
+    sessionId: string;
+    data: SessionData;
+} | null>;
+/**
+ * Rewind a session to a previous user entry.
+ * Returns null for a missing session. NEVER throws.
+ */
+declare function rewindSession(id: string, opts?: {
+    selector?: string;
+}): Promise<SessionData | null>;
+/**
+ * Set the active lineage entry by selector.
+ * Returns null for a missing session. NEVER throws.
+ */
+declare function setActiveEntry(id: string, selector: string): Promise<SessionData | null>;
+interface RunningSessionInfo {
+    readonly pid: number;
+    readonly startedAt: number;
+    readonly cwd: string;
+    /**
+     * Reserved — FEATURE_125 heartbeat schema does not yet carry sessionId.
+     * Will be populated in a future version once the state writer includes it.
+     * Consumers MUST treat undefined as valid; do not assume a running session
+     * always has a sessionId.
+     */
+    readonly sessionId: string | undefined;
+}
+/**
+ * Returns live KodaX sibling instances (excluding this process).
+ * Uses discoverInstances() from @kodax-ai/agent (FEATURE_125 Team Mode).
+ * NEVER throws. Returns [] when no instances directory exists.
+ */
+declare function listRunningSessions(): Promise<RunningSessionInfo[]>;
+type DeleteSessionResult = {
+    ok: true;
+} | {
+    error: {
+        code: 'session_running';
+        runningProcess: {
+            pid: number;
+            startedAt: number;
+        };
+    };
+};
+/**
+ * Delete a session by ID.
+ * Returns { ok: true } on success (including when the session doesn't exist).
+ * Returns an error envelope when the session is currently running.
+ * NEVER throws.
+ */
+declare function deleteSession(id: string): Promise<DeleteSessionResult>;
+/**
+ * Watch the sessions directory for changes.
+ * Returns { close() } that stops the watcher / poll interval.
+ *
+ * Platform branches:
+ * - POSIX: fs.watch() with 100ms debounce.
+ * - Windows: readdir poll every 1000ms, diffed against a snapshot.
+ *
+ * NEVER throws — if the directory doesn't exist the watcher is a no-op
+ * until the directory is created.
+ */
+declare function watchSessions(cb: WatchSessionsCallback): {
+    close: () => void;
+};
+/**
+ * Factory that returns an object with all session management methods bound.
+ *
+ * The `sessionsDir` option is accepted for API surface completeness but is
+ * ignored in v0.7.42 — FileSessionStorage reads KODAX_SESSIONS_DIR frozen at
+ * module-load time. A per-instance directory override requires a substrate-
+ * level `setAgentConfigHome()` call before import. The sessionsDir parameter
+ * will be wired in a future version (v0.7.43 follow-up).
+ */
+declare function createSessionManager(opts?: {
+    sessionsDir?: string;
+}): SessionManager;
+
+export { createSessionManager, deleteSession, forkSession, listRunningSessions, listSessions, loadSession, rewindSession, setActiveEntry, watchSessions };
+export type { DeleteSessionResult, ListSessionsOptions, RunningSessionInfo, SessionManager, SessionSummary, WatchSessionsCallback };

package/dist/sdk-session.js

@@ -0,0 +1,2 @@
+// @kodax-ai/kodax — bundled distribution. See docs/ADR.md ADR-022 + ADR-024.
+import{bc as s,cc as e,dc as n,ec as i,fc as o,gc as t,hc as S,ic as a,jc as r}from"./chunks/chunk-ZZ4KRK2B.js";import"./chunks/chunk-KUX5LRPP.js";import"./chunks/chunk-IYJ5EPRV.js";import"./chunks/chunk-EVIDQWMF.js";import"./chunks/chunk-7JLYVWAF.js";import"./chunks/chunk-CD3R5YBH.js";import"./chunks/chunk-HMYEQJGT.js";import"./chunks/chunk-OWSKU55I.js";import"./chunks/chunk-DKXUY5F2.js";import"./chunks/chunk-3RKBXWZS.js";import"./chunks/chunk-V4WSBIXB.js";export{r as createSessionManager,S as deleteSession,n as forkSession,t as listRunningSessions,s as listSessions,e as loadSession,i as rewindSession,o as setActiveEntry,a as watchSessions};

package/dist/sdk-skills.d.ts

@@ -116,12 +116,68 @@ interface ISkillRegistry {
     /** Number of discovered skills */
     readonly size: number;
 }
+/**
+ * v0.7.42 — SDK-embedder hook for `!`cmd`` dynamic context resolution.
+ *
+ * Receives the literal command string and the working directory the resolver
+ * would have used. Must return the command's text output (which the resolver
+ * splices into the skill markdown in place of the `!`cmd`` token), or throw
+ * to deny.
+ *
+ * **Trust boundary**: when the KodaX SDK is embedded inside a host app
+ * (e.g. KodaX Space, IDE extensions), the host typically mediates shell
+ * execution through a permission broker so the end user can approve / deny
+ * each command. Without this hook, `VariableResolver` directly `execSync`s
+ * commands using its own built-in whitelist — bypassing the host's broker
+ * and producing OS side-effects the user never saw.
+ *
+ * Embedders should route here to:
+ *   - prompt the user via their own UI,
+ *   - log execution to their audit trail,
+ *   - apply policy (e.g. block network commands),
+ *   - or refuse outright (throw).
+ *
+ * @example
+ * ```ts
+ * const context: SkillContext = {
+ *   workingDirectory: '/repo',
+ *   executeDynamicContext: async (cmd, cwd) => {
+ *     const approved = await brokerAskUser({ kind: 'skill-cmd', command: cmd, cwd });
+ *     if (!approved) throw new Error('user denied');
+ *     return await brokerExecute(cmd, cwd);
+ *   },
+ * };
+ * ```
+ */
+type SkillDynamicContextExecutor = (command: string, cwd: string) => Promise<string>;
 interface SkillContext {
     workingDirectory: string;
     projectRoot?: string;
-    sessionId: string;
+    /**
+     * Optional. Used to substitute `${CLAUDE_SESSION_ID}` / `${KODAX_SESSION_ID}`
+     * template variables in skill markdown. Tool-invocation callers (e.g. the
+     * `skill` tool) may not have a session bound — in that case the resolver
+     * falls back to an empty replacement so the substitution doesn't leak the
+     * literal `${...}` to the LLM.
+     */
+    sessionId?: string;
     environment?: Record<string, string>;
     messages?: unknown[];
+    /**
+     * v0.7.42 — SDK-embedder hook for `!`cmd`` dynamic-context resolution.
+     * See {@link SkillDynamicContextExecutor} for the trust-boundary rationale.
+     * When present, completely replaces the built-in `execSync`-based path
+     * (whitelist + 5s timeout). When absent, the legacy whitelist path runs.
+     */
+    executeDynamicContext?: SkillDynamicContextExecutor;
+    /**
+     * v0.7.42 — hard-disable `!`cmd`` resolution.
+     * When `true`, encountering a `!`cmd`` token throws
+     * `[Dynamic context disabled by host]` regardless of any hook. Useful for
+     * embedders that want a single-flag kill switch without writing a hook.
+     * `executeDynamicContext` is ignored when this is `true`.
+     */
+    disableDynamicContext?: boolean;
 }
 interface SkillResult {
     success: boolean;
@@ -273,11 +329,23 @@ declare class VariableResolver implements IVariableResolver {
      */
     private resolveEnvVars;
     /**
-     * Replace !`command` with command output (dynamic context)
+     * Replace !`command` with command output (dynamic context).
+     *
+     * Three-tier dispatch (v0.7.42):
+     *   1. `context.disableDynamicContext === true` → throw immediately,
+     *      surfaced to the LLM as `[Error: …]`. Host-level kill switch.
+     *   2. `context.executeDynamicContext` provided → route there. Embedder
+     *      mediates shell execution (broker, audit, deny).
+     *   3. else → legacy built-in path (`isSafeDynamicContextCommand`
+     *      whitelist + `execSync` with 5s timeout).
+     *
+     * The resolver inlines an `[Error: …]` placeholder for any thrown
+     * exception so a single bad token doesn't poison the whole skill load.
      */
     private resolveDynamicContext;
     /**
-     * Execute a dynamic context command
+     * Execute a dynamic context command via the appropriate dispatch tier.
+     * See `resolveDynamicContext` JSDoc for the 3-tier ordering rationale.
      */
     private executeDynamicCommand;
 }
@@ -489,4 +557,4 @@ declare function expandSkillForLLM(skill: Skill, args: string, context: SkillCon
 declare function formatSkillActivationMessage(skillName: string, args: string): string;
 
 export { SkillExecutor, SkillRegistry, VariableResolver, clearPluginSkillPaths, createExecutor, createResolver, discoverSkills, discoverSkillsWithMonorepo, executeSkill, expandSkillForLLM, formatSkillActivationMessage, getDefaultSkillPaths, getNestedSkillPaths, getSkillPathsFlat, getSkillRegistry, initializeSkillRegistry, listPluginSkillPaths, loadFullSkill, loadSkillFileContent, loadSkillMetadata, parseArguments, parseSkillMarkdown, registerPluginSkillPath, resetSkillRegistry, resolveSkillContent, unregisterPluginSkillPath };
-export type { DiscoveryResult, ExecutionMode, ExecutionOptions, ISkillRegistry, IVariableResolver, Skill, SkillArtifact, SkillContext, SkillExpansionResult, SkillFile, SkillFrontmatter, SkillHook, SkillHooks, SkillMetadata, SkillPathsConfig, SkillResult, SkillSource };
+export type { DiscoveryResult, ExecutionMode, ExecutionOptions, ISkillRegistry, IVariableResolver, Skill, SkillArtifact, SkillContext, SkillDynamicContextExecutor, SkillExpansionResult, SkillFile, SkillFrontmatter, SkillHook, SkillHooks, SkillMetadata, SkillPathsConfig, SkillResult, SkillSource };

package/dist/sdk-skills.js

@@ -1,2 +1,2 @@
 // @kodax-ai/kodax — bundled distribution. See docs/ADR.md ADR-022 + ADR-024.
-import{A as w,B as y,C as z,a as o,b as r,c as e,d as f,e as m,f as p,j as t,k as x,l as a,m as b,n as c,o as d,p as g,q as h,r as i,s as j,t as k,u as l,v as n,w as q,x as s,y as u,z as v}from"./chunks/chunk-EQ5DGS2W.js";import"./chunks/chunk-V4WSBIXB.js";export{u as SkillExecutor,l as SkillRegistry,i as VariableResolver,f as clearPluginSkillPaths,v as createExecutor,j as createResolver,c as discoverSkills,g as discoverSkillsWithMonorepo,w as executeSkill,y as expandSkillForLLM,z as formatSkillActivationMessage,m as getDefaultSkillPaths,d as getNestedSkillPaths,p as getSkillPathsFlat,n as getSkillRegistry,q as initializeSkillRegistry,e as listPluginSkillPaths,a as loadFullSkill,b as loadSkillFileContent,x as loadSkillMetadata,h as parseArguments,t as parseSkillMarkdown,o as registerPluginSkillPath,s as resetSkillRegistry,k as resolveSkillContent,r as unregisterPluginSkillPath};
+import{A as w,B as y,C as z,a as o,b as r,c as e,d as f,e as m,f as p,j as t,k as x,l as a,m as b,n as c,o as d,p as g,q as h,r as i,s as j,t as k,u as l,v as n,w as q,x as s,y as u,z as v}from"./chunks/chunk-OWSKU55I.js";import"./chunks/chunk-V4WSBIXB.js";export{u as SkillExecutor,l as SkillRegistry,i as VariableResolver,f as clearPluginSkillPaths,v as createExecutor,j as createResolver,c as discoverSkills,g as discoverSkillsWithMonorepo,w as executeSkill,y as expandSkillForLLM,z as formatSkillActivationMessage,m as getDefaultSkillPaths,d as getNestedSkillPaths,p as getSkillPathsFlat,n as getSkillRegistry,q as initializeSkillRegistry,e as listPluginSkillPaths,a as loadFullSkill,b as loadSkillFileContent,x as loadSkillMetadata,h as parseArguments,t as parseSkillMarkdown,o as registerPluginSkillPath,s as resetSkillRegistry,k as resolveSkillContent,r as unregisterPluginSkillPath};