@aumos/agent-session-linker 0.1.0

package/dist/client.d.ts

@@ -0,0 +1,100 @@
+/**
+ * HTTP client for the agent-session-linker session management API.
+ *
+ * Uses the Fetch API (available natively in Node 18+, browsers, and Deno).
+ * No external dependencies required.
+ *
+ * @example
+ * ```ts
+ * import { createAgentSessionLinkerClient } from "@aumos/agent-session-linker";
+ *
+ * const client = createAgentSessionLinkerClient({ baseUrl: "http://localhost:8091" });
+ *
+ * const session = await client.createSession({ agent_id: "my-agent" });
+ * if (session.ok) {
+ *   console.log("Session created:", session.data.session_id);
+ * }
+ * ```
+ */
+import type { ApiResult, CreateSessionRequest, ResumptionToken, ResumeSessionRequest, SaveContextRequest, SessionState, SessionStats, SessionSummary } from "./types.js";
+/** Configuration options for the AgentSessionLinkerClient. */
+export interface AgentSessionLinkerClientConfig {
+    /** Base URL of the agent-session-linker server (e.g. "http://localhost:8091"). */
+    readonly baseUrl: string;
+    /** Optional request timeout in milliseconds (default: 30000). */
+    readonly timeoutMs?: number;
+    /** Optional extra HTTP headers sent with every request. */
+    readonly headers?: Readonly<Record<string, string>>;
+}
+/** Typed HTTP client for the agent-session-linker server. */
+export interface AgentSessionLinkerClient {
+    /**
+     * Create a new agent session.
+     *
+     * @param request - Optional session creation parameters including agent_id and preferences.
+     * @returns The newly created SessionState record.
+     */
+    createSession(request?: CreateSessionRequest): Promise<ApiResult<SessionState>>;
+    /**
+     * Retrieve a session by its unique identifier.
+     *
+     * @param sessionId - The session to retrieve.
+     * @returns The full SessionState for the requested session.
+     */
+    getSession(sessionId: string): Promise<ApiResult<SessionState>>;
+    /**
+     * Resume a session using a previously issued resumption token.
+     *
+     * @param request - Contains the opaque resumption token.
+     * @returns The deserialised SessionState linked to the token.
+     */
+    resumeSession(request: ResumeSessionRequest): Promise<ApiResult<SessionState>>;
+    /**
+     * Save or update the context payload for an existing session.
+     *
+     * @param request - Contains the session_id and partial context fields to update.
+     * @returns The updated SessionState after the save operation.
+     */
+    saveContext(request: SaveContextRequest): Promise<ApiResult<SessionState>>;
+    /**
+     * List all sessions, optionally filtered by agent identifier.
+     *
+     * @param options - Optional filter parameters.
+     * @returns Array of SessionSummary records ordered by creation time descending.
+     */
+    listSessions(options?: {
+        readonly agentId?: string;
+        readonly limit?: number;
+    }): Promise<ApiResult<readonly SessionSummary[]>>;
+    /**
+     * Delete a session from the session store.
+     *
+     * @param sessionId - The session to delete.
+     * @returns An empty object on successful deletion.
+     */
+    deleteSession(sessionId: string): Promise<ApiResult<Readonly<Record<string, never>>>>;
+    /**
+     * Generate a resumption token for a session to enable cross-boundary transfer.
+     *
+     * @param sessionId - The session for which to generate a token.
+     * @param options - Optional token lifetime in seconds (default: 3600).
+     * @returns A ResumptionToken that can be serialised and passed to resumeSession().
+     */
+    getResumptionToken(sessionId: string, options?: {
+        readonly ttlSeconds?: number;
+    }): Promise<ApiResult<ResumptionToken>>;
+    /**
+     * Retrieve aggregate statistics across all stored sessions.
+     *
+     * @returns A SessionStats record with totals and agent breakdown.
+     */
+    getStats(): Promise<ApiResult<SessionStats>>;
+}
+/**
+ * Create a typed HTTP client for the agent-session-linker server.
+ *
+ * @param config - Client configuration including base URL.
+ * @returns An AgentSessionLinkerClient instance.
+ */
+export declare function createAgentSessionLinkerClient(config: AgentSessionLinkerClientConfig): AgentSessionLinkerClient;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAEV,SAAS,EACT,oBAAoB,EACpB,eAAe,EACf,oBAAoB,EACpB,kBAAkB,EAClB,YAAY,EACZ,YAAY,EACZ,cAAc,EACf,MAAM,YAAY,CAAC;AAMpB,8DAA8D;AAC9D,MAAM,WAAW,8BAA8B;IAC7C,kFAAkF;IAClF,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,iEAAiE;IACjE,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,2DAA2D;IAC3D,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACrD;AA0DD,6DAA6D;AAC7D,MAAM,WAAW,wBAAwB;IACvC;;;;;OAKG;IACH,aAAa,CAAC,OAAO,CAAC,EAAE,oBAAoB,GAAG,OAAO,CAAC,SAAS,CAAC,YAAY,CAAC,CAAC,CAAC;IAEhF;;;;;OAKG;IACH,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC,YAAY,CAAC,CAAC,CAAC;IAEhE;;;;;OAKG;IACH,aAAa,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,SAAS,CAAC,YAAY,CAAC,CAAC,CAAC;IAE/E;;;;;OAKG;IACH,WAAW,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,SAAS,CAAC,YAAY,CAAC,CAAC,CAAC;IAE3E;;;;;OAKG;IACH,YAAY,CAAC,OAAO,CAAC,EAAE;QACrB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;QAC1B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;KACzB,GAAG,OAAO,CAAC,SAAS,CAAC,SAAS,cAAc,EAAE,CAAC,CAAC,CAAC;IAElD;;;;;OAKG;IACH,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IAEtF;;;;;;OAMG;IACH,kBAAkB,CAChB,SAAS,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,GACzC,OAAO,CAAC,SAAS,CAAC,eAAe,CAAC,CAAC,CAAC;IAEvC;;;;OAIG;IACH,QAAQ,IAAI,OAAO,CAAC,SAAS,CAAC,YAAY,CAAC,CAAC,CAAC;CAC9C;AAMD;;;;;GAKG;AACH,wBAAgB,8BAA8B,CAC5C,MAAM,EAAE,8BAA8B,GACrC,wBAAwB,CAkH1B"}

package/dist/client.js

@@ -0,0 +1,129 @@
+/**
+ * HTTP client for the agent-session-linker session management API.
+ *
+ * Uses the Fetch API (available natively in Node 18+, browsers, and Deno).
+ * No external dependencies required.
+ *
+ * @example
+ * ```ts
+ * import { createAgentSessionLinkerClient } from "@aumos/agent-session-linker";
+ *
+ * const client = createAgentSessionLinkerClient({ baseUrl: "http://localhost:8091" });
+ *
+ * const session = await client.createSession({ agent_id: "my-agent" });
+ * if (session.ok) {
+ *   console.log("Session created:", session.data.session_id);
+ * }
+ * ```
+ */
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+async function fetchJson(url, init, timeoutMs) {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const response = await fetch(url, { ...init, signal: controller.signal });
+        clearTimeout(timeoutId);
+        const body = await response.json();
+        if (!response.ok) {
+            const errorBody = body;
+            return {
+                ok: false,
+                error: {
+                    error: errorBody.error ?? "Unknown error",
+                    detail: errorBody.detail ?? "",
+                },
+                status: response.status,
+            };
+        }
+        return { ok: true, data: body };
+    }
+    catch (err) {
+        clearTimeout(timeoutId);
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            ok: false,
+            error: { error: "Network error", detail: message },
+            status: 0,
+        };
+    }
+}
+function buildHeaders(extraHeaders) {
+    return {
+        "Content-Type": "application/json",
+        Accept: "application/json",
+        ...extraHeaders,
+    };
+}
+// ---------------------------------------------------------------------------
+// Client factory
+// ---------------------------------------------------------------------------
+/**
+ * Create a typed HTTP client for the agent-session-linker server.
+ *
+ * @param config - Client configuration including base URL.
+ * @returns An AgentSessionLinkerClient instance.
+ */
+export function createAgentSessionLinkerClient(config) {
+    const { baseUrl, timeoutMs = 30000, headers: extraHeaders } = config;
+    const baseHeaders = buildHeaders(extraHeaders);
+    return {
+        async createSession(request) {
+            return fetchJson(`${baseUrl}/sessions`, {
+                method: "POST",
+                headers: baseHeaders,
+                body: JSON.stringify(request ?? {}),
+            }, timeoutMs);
+        },
+        async getSession(sessionId) {
+            return fetchJson(`${baseUrl}/sessions/${encodeURIComponent(sessionId)}`, { method: "GET", headers: baseHeaders }, timeoutMs);
+        },
+        async resumeSession(request) {
+            return fetchJson(`${baseUrl}/sessions/resume`, {
+                method: "POST",
+                headers: baseHeaders,
+                body: JSON.stringify(request),
+            }, timeoutMs);
+        },
+        async saveContext(request) {
+            return fetchJson(`${baseUrl}/sessions/${encodeURIComponent(request.session_id)}/context`, {
+                method: "PATCH",
+                headers: baseHeaders,
+                body: JSON.stringify(request.context),
+            }, timeoutMs);
+        },
+        async listSessions(options) {
+            const params = new URLSearchParams();
+            if (options?.agentId !== undefined) {
+                params.set("agent_id", options.agentId);
+            }
+            if (options?.limit !== undefined) {
+                params.set("limit", String(options.limit));
+            }
+            const queryString = params.toString();
+            const url = queryString
+                ? `${baseUrl}/sessions?${queryString}`
+                : `${baseUrl}/sessions`;
+            return fetchJson(url, { method: "GET", headers: baseHeaders }, timeoutMs);
+        },
+        async deleteSession(sessionId) {
+            return fetchJson(`${baseUrl}/sessions/${encodeURIComponent(sessionId)}`, { method: "DELETE", headers: baseHeaders }, timeoutMs);
+        },
+        async getResumptionToken(sessionId, options) {
+            const params = new URLSearchParams();
+            if (options?.ttlSeconds !== undefined) {
+                params.set("ttl_seconds", String(options.ttlSeconds));
+            }
+            const queryString = params.toString();
+            const url = queryString
+                ? `${baseUrl}/sessions/${encodeURIComponent(sessionId)}/token?${queryString}`
+                : `${baseUrl}/sessions/${encodeURIComponent(sessionId)}/token`;
+            return fetchJson(url, { method: "POST", headers: baseHeaders, body: JSON.stringify({}) }, timeoutMs);
+        },
+        async getStats() {
+            return fetchJson(`${baseUrl}/sessions/stats`, { method: "GET", headers: baseHeaders }, timeoutMs);
+        },
+    };
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @aumos/agent-session-linker
+ *
+ * TypeScript client for the AumOS agent-session-linker library.
+ * Provides HTTP client and session type definitions for cross-session
+ * context persistence, resumption tokens, and session lifecycle management.
+ */
+export type { AgentSessionLinkerClient, AgentSessionLinkerClientConfig } from "./client.js";
+export { createAgentSessionLinkerClient } from "./client.js";
+export type { TaskStatus, ContextSegment, EntityReference, TaskState, ToolContext, SessionState, CreateSessionRequest, ResumeSessionRequest, SaveContextRequest, ResumptionToken, SessionSummary, SessionStats, ApiError, ApiResult, } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,YAAY,EAAE,wBAAwB,EAAE,8BAA8B,EAAE,MAAM,aAAa,CAAC;AAC5F,OAAO,EAAE,8BAA8B,EAAE,MAAM,aAAa,CAAC;AAG7D,YAAY,EACV,UAAU,EACV,cAAc,EACd,eAAe,EACf,SAAS,EACT,WAAW,EACX,YAAY,EACZ,oBAAoB,EACpB,oBAAoB,EACpB,kBAAkB,EAClB,eAAe,EACf,cAAc,EACd,YAAY,EACZ,QAAQ,EACR,SAAS,GACV,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,9 @@
+/**
+ * @aumos/agent-session-linker
+ *
+ * TypeScript client for the AumOS agent-session-linker library.
+ * Provides HTTP client and session type definitions for cross-session
+ * context persistence, resumption tokens, and session lifecycle management.
+ */
+export { createAgentSessionLinkerClient } from "./client.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,EAAE,8BAA8B,EAAE,MAAM,aAAa,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,227 @@
+/**
+ * TypeScript interfaces for the agent-session-linker session management library.
+ *
+ * Mirrors the Pydantic models defined in:
+ *   agent_session_linker.session.state
+ *   agent_session_linker.session.manager
+ *   agent_session_linker.session.serializer
+ *
+ * All interfaces use readonly fields to match Python's frozen Pydantic models.
+ */
+/**
+ * Lifecycle state of a tracked task within a session.
+ * Maps to TaskStatus enum in Python.
+ */
+export type TaskStatus = "pending" | "in_progress" | "completed" | "failed" | "cancelled";
+/**
+ * A discrete unit of context captured from a single conversation turn.
+ * Maps to ContextSegment in Python.
+ */
+export interface ContextSegment {
+    /** Unique identifier for this segment. */
+    readonly segment_id: string;
+    /** Message role: "user", "assistant", "system", or "tool". */
+    readonly role: string;
+    /** Raw text content of the segment. */
+    readonly content: string;
+    /** Estimated token count for this segment. */
+    readonly token_count: number;
+    /** Categorical label such as "conversation", "reasoning", "code", "plan", "output", or "metadata". */
+    readonly segment_type: string;
+    /** ISO-8601 UTC timestamp when this segment was captured. */
+    readonly timestamp: string;
+    /** Zero-based index of the conversation turn this segment belongs to. */
+    readonly turn_index: number;
+    /** Arbitrary additional key-value data attached to this segment. */
+    readonly metadata: Readonly<Record<string, string>>;
+}
+/**
+ * A cross-session pointer to a tracked domain entity.
+ * Maps to EntityReference in Python.
+ */
+export interface EntityReference {
+    /** Unique identifier for this entity record. */
+    readonly entity_id: string;
+    /** Primary normalised name used for matching. */
+    readonly canonical_name: string;
+    /** Categorical label such as "person", "project", "file", "concept", "tool", or "organisation". */
+    readonly entity_type: string;
+    /** Alternative names or spellings for this entity. */
+    readonly aliases: readonly string[];
+    /** Key-value attributes describing the entity. */
+    readonly attributes: Readonly<Record<string, string>>;
+    /** Session ID where this entity was first observed. */
+    readonly first_seen_session: string;
+    /** Session ID where this entity was most recently observed. */
+    readonly last_seen_session: string;
+    /** Match/extraction confidence in the range [0.0, 1.0]. */
+    readonly confidence: number;
+}
+/**
+ * A tracked task with its current lifecycle status.
+ * Maps to TaskState in Python.
+ */
+export interface TaskState {
+    /** Unique identifier for this task. */
+    readonly task_id: string;
+    /** Short human-readable title. */
+    readonly title: string;
+    /** Detailed description of what the task requires. */
+    readonly description: string;
+    /** Current lifecycle status. */
+    readonly status: TaskStatus;
+    /** Integer priority where 1 is highest. Range [1, 10]. */
+    readonly priority: number;
+    /** ISO-8601 UTC timestamp when the task was first recorded. */
+    readonly created_at: string;
+    /** ISO-8601 UTC timestamp when the task was last modified. */
+    readonly updated_at: string;
+    /** Optional reference to a parent task for sub-task hierarchies. */
+    readonly parent_task_id: string | null;
+    /** Free-form labels for categorisation and filtering. */
+    readonly tags: readonly string[];
+    /** Additional free-text notes about the task. */
+    readonly notes: string;
+}
+/**
+ * A record of a single tool invocation within a session.
+ * Maps to ToolContext in Python.
+ */
+export interface ToolContext {
+    /** Unique identifier for this invocation. */
+    readonly invocation_id: string;
+    /** Name of the tool that was called. */
+    readonly tool_name: string;
+    /** Brief summary of the input arguments (not the full payload). */
+    readonly input_summary: string;
+    /** Brief summary of the output returned. */
+    readonly output_summary: string;
+    /** Wall-clock execution time in milliseconds. */
+    readonly duration_ms: number;
+    /** Whether the invocation completed without error. */
+    readonly success: boolean;
+    /** Error description when success is false. */
+    readonly error_message: string;
+    /** ISO-8601 UTC timestamp when the invocation started. */
+    readonly timestamp: string;
+    /** Tokens consumed by the tool call, if measurable. */
+    readonly token_cost: number;
+}
+/**
+ * Complete snapshot of an agent session.
+ * Maps to SessionState in Python.
+ */
+export interface SessionState {
+    /** Globally unique session identifier. */
+    readonly session_id: string;
+    /** Identifier for the agent or agent-type that owns this session. */
+    readonly agent_id: string;
+    /** Schema version string used for forward/backward compatibility. */
+    readonly schema_version: string;
+    /** Ordered list of conversation context segments. */
+    readonly segments: readonly ContextSegment[];
+    /** Named entities tracked within this session. */
+    readonly entities: readonly EntityReference[];
+    /** Tasks created or referenced during this session. */
+    readonly tasks: readonly TaskState[];
+    /** Chronological log of tool invocations. */
+    readonly tools_used: readonly ToolContext[];
+    /** Agent or user preferences captured during the session. */
+    readonly preferences: Readonly<Record<string, string>>;
+    /** Optional compressed summary of the session's key content. */
+    readonly summary: string;
+    /** If this is a continuation, the ID of the preceding session. */
+    readonly parent_session_id: string | null;
+    /** Accumulated LLM API cost in USD for this session. */
+    readonly total_cost_usd: number;
+    /** ISO-8601 UTC timestamp of session creation. */
+    readonly created_at: string;
+    /** ISO-8601 UTC timestamp of last modification. */
+    readonly updated_at: string;
+    /** SHA-256 of the session's canonical JSON (excluding this field). */
+    readonly checksum: string;
+}
+/** Configuration for creating a new session. */
+export interface CreateSessionRequest {
+    /** Agent identifier that owns this session. */
+    readonly agent_id?: string;
+    /** Optional parent session to create a continuation from. */
+    readonly parent_session_id?: string;
+    /** Initial preference key-value pairs. */
+    readonly preferences?: Readonly<Record<string, string>>;
+}
+/** Request to resume a session using a resumption token. */
+export interface ResumeSessionRequest {
+    /** The opaque resumption token previously issued by the server. */
+    readonly resumption_token: string;
+}
+/** Request to save a serialised context payload. */
+export interface SaveContextRequest {
+    /** The session ID to update. */
+    readonly session_id: string;
+    /** Partial or full updated session state fields. */
+    readonly context: Partial<Pick<SessionState, "segments" | "entities" | "tasks" | "tools_used" | "preferences" | "summary" | "total_cost_usd">>;
+}
+/**
+ * An opaque token that enables resuming a serialised session across boundaries.
+ * Maps to the resumption token concept in agent_session_linker.portable.
+ */
+export interface ResumptionToken {
+    /** The token value to pass to resumeSession(). */
+    readonly token: string;
+    /** Session ID this token references. */
+    readonly session_id: string;
+    /** ISO-8601 UTC timestamp after which this token expires. */
+    readonly expires_at: string;
+    /** Schema version of the serialised payload. */
+    readonly schema_version: string;
+}
+/** Summary information returned when listing sessions. */
+export interface SessionSummary {
+    /** Unique session identifier. */
+    readonly session_id: string;
+    /** Agent that owns this session. */
+    readonly agent_id: string;
+    /** ISO-8601 UTC creation timestamp. */
+    readonly created_at: string;
+    /** ISO-8601 UTC last-update timestamp. */
+    readonly updated_at: string;
+    /** Total number of context segments. */
+    readonly segment_count: number;
+    /** Total number of tracked tasks. */
+    readonly task_count: number;
+    /** Whether this session has a parent (is a continuation). */
+    readonly is_continuation: boolean;
+}
+/** Aggregate statistics across all stored sessions. */
+export interface SessionStats {
+    /** Total number of stored sessions. */
+    readonly total_sessions: number;
+    /** Sum of all segment counts across sessions. */
+    readonly total_segments: number;
+    /** Sum of all token counts across sessions. */
+    readonly total_tokens: number;
+    /** Sum of all task counts across sessions. */
+    readonly total_tasks: number;
+    /** Sum of all entity counts across sessions. */
+    readonly total_entities: number;
+    /** Summed cost across all sessions in USD. */
+    readonly total_cost_usd: number;
+    /** List of unique agent IDs that have sessions. */
+    readonly agents: readonly string[];
+}
+/** Standard error payload returned by the agent-session-linker API. */
+export interface ApiError {
+    readonly error: string;
+    readonly detail: string;
+}
+/** Result type for all client operations. */
+export type ApiResult<T> = {
+    readonly ok: true;
+    readonly data: T;
+} | {
+    readonly ok: false;
+    readonly error: ApiError;
+    readonly status: number;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,12 @@
+/**
+ * TypeScript interfaces for the agent-session-linker session management library.
+ *
+ * Mirrors the Pydantic models defined in:
+ *   agent_session_linker.session.state
+ *   agent_session_linker.session.manager
+ *   agent_session_linker.session.serializer
+ *
+ * All interfaces use readonly fields to match Python's frozen Pydantic models.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG"}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@aumos/agent-session-linker",
+  "version": "0.1.0",
+  "description": "TypeScript client for the AumOS agent-session-linker — cross-session context persistence, resumption tokens, and session lifecycle management",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "typescript": "^5.3.0"
+  },
+  "keywords": [
+    "aumos",
+    "agent-session-linker",
+    "session",
+    "context",
+    "resumption",
+    "typescript"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/aumos-ai/agent-session-linker"
+  }
+}

package/src/client.ts

@@ -0,0 +1,302 @@
+/**
+ * HTTP client for the agent-session-linker session management API.
+ *
+ * Uses the Fetch API (available natively in Node 18+, browsers, and Deno).
+ * No external dependencies required.
+ *
+ * @example
+ * ```ts
+ * import { createAgentSessionLinkerClient } from "@aumos/agent-session-linker";
+ *
+ * const client = createAgentSessionLinkerClient({ baseUrl: "http://localhost:8091" });
+ *
+ * const session = await client.createSession({ agent_id: "my-agent" });
+ * if (session.ok) {
+ *   console.log("Session created:", session.data.session_id);
+ * }
+ * ```
+ */
+
+import type {
+  ApiError,
+  ApiResult,
+  CreateSessionRequest,
+  ResumptionToken,
+  ResumeSessionRequest,
+  SaveContextRequest,
+  SessionState,
+  SessionStats,
+  SessionSummary,
+} from "./types.js";
+
+// ---------------------------------------------------------------------------
+// Client configuration
+// ---------------------------------------------------------------------------
+
+/** Configuration options for the AgentSessionLinkerClient. */
+export interface AgentSessionLinkerClientConfig {
+  /** Base URL of the agent-session-linker server (e.g. "http://localhost:8091"). */
+  readonly baseUrl: string;
+  /** Optional request timeout in milliseconds (default: 30000). */
+  readonly timeoutMs?: number;
+  /** Optional extra HTTP headers sent with every request. */
+  readonly headers?: Readonly<Record<string, string>>;
+}
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+async function fetchJson<T>(
+  url: string,
+  init: RequestInit,
+  timeoutMs: number,
+): Promise<ApiResult<T>> {
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+
+  try {
+    const response = await fetch(url, { ...init, signal: controller.signal });
+    clearTimeout(timeoutId);
+
+    const body = await response.json() as unknown;
+
+    if (!response.ok) {
+      const errorBody = body as Partial<ApiError>;
+      return {
+        ok: false,
+        error: {
+          error: errorBody.error ?? "Unknown error",
+          detail: errorBody.detail ?? "",
+        },
+        status: response.status,
+      };
+    }
+
+    return { ok: true, data: body as T };
+  } catch (err: unknown) {
+    clearTimeout(timeoutId);
+    const message = err instanceof Error ? err.message : String(err);
+    return {
+      ok: false,
+      error: { error: "Network error", detail: message },
+      status: 0,
+    };
+  }
+}
+
+function buildHeaders(
+  extraHeaders: Readonly<Record<string, string>> | undefined,
+): Record<string, string> {
+  return {
+    "Content-Type": "application/json",
+    Accept: "application/json",
+    ...extraHeaders,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Client interface
+// ---------------------------------------------------------------------------
+
+/** Typed HTTP client for the agent-session-linker server. */
+export interface AgentSessionLinkerClient {
+  /**
+   * Create a new agent session.
+   *
+   * @param request - Optional session creation parameters including agent_id and preferences.
+   * @returns The newly created SessionState record.
+   */
+  createSession(request?: CreateSessionRequest): Promise<ApiResult<SessionState>>;
+
+  /**
+   * Retrieve a session by its unique identifier.
+   *
+   * @param sessionId - The session to retrieve.
+   * @returns The full SessionState for the requested session.
+   */
+  getSession(sessionId: string): Promise<ApiResult<SessionState>>;
+
+  /**
+   * Resume a session using a previously issued resumption token.
+   *
+   * @param request - Contains the opaque resumption token.
+   * @returns The deserialised SessionState linked to the token.
+   */
+  resumeSession(request: ResumeSessionRequest): Promise<ApiResult<SessionState>>;
+
+  /**
+   * Save or update the context payload for an existing session.
+   *
+   * @param request - Contains the session_id and partial context fields to update.
+   * @returns The updated SessionState after the save operation.
+   */
+  saveContext(request: SaveContextRequest): Promise<ApiResult<SessionState>>;
+
+  /**
+   * List all sessions, optionally filtered by agent identifier.
+   *
+   * @param options - Optional filter parameters.
+   * @returns Array of SessionSummary records ordered by creation time descending.
+   */
+  listSessions(options?: {
+    readonly agentId?: string;
+    readonly limit?: number;
+  }): Promise<ApiResult<readonly SessionSummary[]>>;
+
+  /**
+   * Delete a session from the session store.
+   *
+   * @param sessionId - The session to delete.
+   * @returns An empty object on successful deletion.
+   */
+  deleteSession(sessionId: string): Promise<ApiResult<Readonly<Record<string, never>>>>;
+
+  /**
+   * Generate a resumption token for a session to enable cross-boundary transfer.
+   *
+   * @param sessionId - The session for which to generate a token.
+   * @param options - Optional token lifetime in seconds (default: 3600).
+   * @returns A ResumptionToken that can be serialised and passed to resumeSession().
+   */
+  getResumptionToken(
+    sessionId: string,
+    options?: { readonly ttlSeconds?: number },
+  ): Promise<ApiResult<ResumptionToken>>;
+
+  /**
+   * Retrieve aggregate statistics across all stored sessions.
+   *
+   * @returns A SessionStats record with totals and agent breakdown.
+   */
+  getStats(): Promise<ApiResult<SessionStats>>;
+}
+
+// ---------------------------------------------------------------------------
+// Client factory
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a typed HTTP client for the agent-session-linker server.
+ *
+ * @param config - Client configuration including base URL.
+ * @returns An AgentSessionLinkerClient instance.
+ */
+export function createAgentSessionLinkerClient(
+  config: AgentSessionLinkerClientConfig,
+): AgentSessionLinkerClient {
+  const { baseUrl, timeoutMs = 30_000, headers: extraHeaders } = config;
+  const baseHeaders = buildHeaders(extraHeaders);
+
+  return {
+    async createSession(
+      request?: CreateSessionRequest,
+    ): Promise<ApiResult<SessionState>> {
+      return fetchJson<SessionState>(
+        `${baseUrl}/sessions`,
+        {
+          method: "POST",
+          headers: baseHeaders,
+          body: JSON.stringify(request ?? {}),
+        },
+        timeoutMs,
+      );
+    },
+
+    async getSession(sessionId: string): Promise<ApiResult<SessionState>> {
+      return fetchJson<SessionState>(
+        `${baseUrl}/sessions/${encodeURIComponent(sessionId)}`,
+        { method: "GET", headers: baseHeaders },
+        timeoutMs,
+      );
+    },
+
+    async resumeSession(
+      request: ResumeSessionRequest,
+    ): Promise<ApiResult<SessionState>> {
+      return fetchJson<SessionState>(
+        `${baseUrl}/sessions/resume`,
+        {
+          method: "POST",
+          headers: baseHeaders,
+          body: JSON.stringify(request),
+        },
+        timeoutMs,
+      );
+    },
+
+    async saveContext(
+      request: SaveContextRequest,
+    ): Promise<ApiResult<SessionState>> {
+      return fetchJson<SessionState>(
+        `${baseUrl}/sessions/${encodeURIComponent(request.session_id)}/context`,
+        {
+          method: "PATCH",
+          headers: baseHeaders,
+          body: JSON.stringify(request.context),
+        },
+        timeoutMs,
+      );
+    },
+
+    async listSessions(options?: {
+      readonly agentId?: string;
+      readonly limit?: number;
+    }): Promise<ApiResult<readonly SessionSummary[]>> {
+      const params = new URLSearchParams();
+      if (options?.agentId !== undefined) {
+        params.set("agent_id", options.agentId);
+      }
+      if (options?.limit !== undefined) {
+        params.set("limit", String(options.limit));
+      }
+      const queryString = params.toString();
+      const url = queryString
+        ? `${baseUrl}/sessions?${queryString}`
+        : `${baseUrl}/sessions`;
+      return fetchJson<readonly SessionSummary[]>(
+        url,
+        { method: "GET", headers: baseHeaders },
+        timeoutMs,
+      );
+    },
+
+    async deleteSession(
+      sessionId: string,
+    ): Promise<ApiResult<Readonly<Record<string, never>>>> {
+      return fetchJson<Readonly<Record<string, never>>>(
+        `${baseUrl}/sessions/${encodeURIComponent(sessionId)}`,
+        { method: "DELETE", headers: baseHeaders },
+        timeoutMs,
+      );
+    },
+
+    async getResumptionToken(
+      sessionId: string,
+      options?: { readonly ttlSeconds?: number },
+    ): Promise<ApiResult<ResumptionToken>> {
+      const params = new URLSearchParams();
+      if (options?.ttlSeconds !== undefined) {
+        params.set("ttl_seconds", String(options.ttlSeconds));
+      }
+      const queryString = params.toString();
+      const url = queryString
+        ? `${baseUrl}/sessions/${encodeURIComponent(sessionId)}/token?${queryString}`
+        : `${baseUrl}/sessions/${encodeURIComponent(sessionId)}/token`;
+      return fetchJson<ResumptionToken>(
+        url,
+        { method: "POST", headers: baseHeaders, body: JSON.stringify({}) },
+        timeoutMs,
+      );
+    },
+
+    async getStats(): Promise<ApiResult<SessionStats>> {
+      return fetchJson<SessionStats>(
+        `${baseUrl}/sessions/stats`,
+        { method: "GET", headers: baseHeaders },
+        timeoutMs,
+      );
+    },
+  };
+}
+

package/src/index.ts

@@ -0,0 +1,29 @@
+/**
+ * @aumos/agent-session-linker
+ *
+ * TypeScript client for the AumOS agent-session-linker library.
+ * Provides HTTP client and session type definitions for cross-session
+ * context persistence, resumption tokens, and session lifecycle management.
+ */
+
+// Client and configuration
+export type { AgentSessionLinkerClient, AgentSessionLinkerClientConfig } from "./client.js";
+export { createAgentSessionLinkerClient } from "./client.js";
+
+// Core types
+export type {
+  TaskStatus,
+  ContextSegment,
+  EntityReference,
+  TaskState,
+  ToolContext,
+  SessionState,
+  CreateSessionRequest,
+  ResumeSessionRequest,
+  SaveContextRequest,
+  ResumptionToken,
+  SessionSummary,
+  SessionStats,
+  ApiError,
+  ApiResult,
+} from "./types.js";

package/src/types.ts

@@ -0,0 +1,286 @@
+/**
+ * TypeScript interfaces for the agent-session-linker session management library.
+ *
+ * Mirrors the Pydantic models defined in:
+ *   agent_session_linker.session.state
+ *   agent_session_linker.session.manager
+ *   agent_session_linker.session.serializer
+ *
+ * All interfaces use readonly fields to match Python's frozen Pydantic models.
+ */
+
+// ---------------------------------------------------------------------------
+// Task lifecycle
+// ---------------------------------------------------------------------------
+
+/**
+ * Lifecycle state of a tracked task within a session.
+ * Maps to TaskStatus enum in Python.
+ */
+export type TaskStatus =
+  | "pending"
+  | "in_progress"
+  | "completed"
+  | "failed"
+  | "cancelled";
+
+// ---------------------------------------------------------------------------
+// Context segment
+// ---------------------------------------------------------------------------
+
+/**
+ * A discrete unit of context captured from a single conversation turn.
+ * Maps to ContextSegment in Python.
+ */
+export interface ContextSegment {
+  /** Unique identifier for this segment. */
+  readonly segment_id: string;
+  /** Message role: "user", "assistant", "system", or "tool". */
+  readonly role: string;
+  /** Raw text content of the segment. */
+  readonly content: string;
+  /** Estimated token count for this segment. */
+  readonly token_count: number;
+  /** Categorical label such as "conversation", "reasoning", "code", "plan", "output", or "metadata". */
+  readonly segment_type: string;
+  /** ISO-8601 UTC timestamp when this segment was captured. */
+  readonly timestamp: string;
+  /** Zero-based index of the conversation turn this segment belongs to. */
+  readonly turn_index: number;
+  /** Arbitrary additional key-value data attached to this segment. */
+  readonly metadata: Readonly<Record<string, string>>;
+}
+
+// ---------------------------------------------------------------------------
+// Entity reference
+// ---------------------------------------------------------------------------
+
+/**
+ * A cross-session pointer to a tracked domain entity.
+ * Maps to EntityReference in Python.
+ */
+export interface EntityReference {
+  /** Unique identifier for this entity record. */
+  readonly entity_id: string;
+  /** Primary normalised name used for matching. */
+  readonly canonical_name: string;
+  /** Categorical label such as "person", "project", "file", "concept", "tool", or "organisation". */
+  readonly entity_type: string;
+  /** Alternative names or spellings for this entity. */
+  readonly aliases: readonly string[];
+  /** Key-value attributes describing the entity. */
+  readonly attributes: Readonly<Record<string, string>>;
+  /** Session ID where this entity was first observed. */
+  readonly first_seen_session: string;
+  /** Session ID where this entity was most recently observed. */
+  readonly last_seen_session: string;
+  /** Match/extraction confidence in the range [0.0, 1.0]. */
+  readonly confidence: number;
+}
+
+// ---------------------------------------------------------------------------
+// Task state
+// ---------------------------------------------------------------------------
+
+/**
+ * A tracked task with its current lifecycle status.
+ * Maps to TaskState in Python.
+ */
+export interface TaskState {
+  /** Unique identifier for this task. */
+  readonly task_id: string;
+  /** Short human-readable title. */
+  readonly title: string;
+  /** Detailed description of what the task requires. */
+  readonly description: string;
+  /** Current lifecycle status. */
+  readonly status: TaskStatus;
+  /** Integer priority where 1 is highest. Range [1, 10]. */
+  readonly priority: number;
+  /** ISO-8601 UTC timestamp when the task was first recorded. */
+  readonly created_at: string;
+  /** ISO-8601 UTC timestamp when the task was last modified. */
+  readonly updated_at: string;
+  /** Optional reference to a parent task for sub-task hierarchies. */
+  readonly parent_task_id: string | null;
+  /** Free-form labels for categorisation and filtering. */
+  readonly tags: readonly string[];
+  /** Additional free-text notes about the task. */
+  readonly notes: string;
+}
+
+// ---------------------------------------------------------------------------
+// Tool context
+// ---------------------------------------------------------------------------
+
+/**
+ * A record of a single tool invocation within a session.
+ * Maps to ToolContext in Python.
+ */
+export interface ToolContext {
+  /** Unique identifier for this invocation. */
+  readonly invocation_id: string;
+  /** Name of the tool that was called. */
+  readonly tool_name: string;
+  /** Brief summary of the input arguments (not the full payload). */
+  readonly input_summary: string;
+  /** Brief summary of the output returned. */
+  readonly output_summary: string;
+  /** Wall-clock execution time in milliseconds. */
+  readonly duration_ms: number;
+  /** Whether the invocation completed without error. */
+  readonly success: boolean;
+  /** Error description when success is false. */
+  readonly error_message: string;
+  /** ISO-8601 UTC timestamp when the invocation started. */
+  readonly timestamp: string;
+  /** Tokens consumed by the tool call, if measurable. */
+  readonly token_cost: number;
+}
+
+// ---------------------------------------------------------------------------
+// Session state
+// ---------------------------------------------------------------------------
+
+/**
+ * Complete snapshot of an agent session.
+ * Maps to SessionState in Python.
+ */
+export interface SessionState {
+  /** Globally unique session identifier. */
+  readonly session_id: string;
+  /** Identifier for the agent or agent-type that owns this session. */
+  readonly agent_id: string;
+  /** Schema version string used for forward/backward compatibility. */
+  readonly schema_version: string;
+  /** Ordered list of conversation context segments. */
+  readonly segments: readonly ContextSegment[];
+  /** Named entities tracked within this session. */
+  readonly entities: readonly EntityReference[];
+  /** Tasks created or referenced during this session. */
+  readonly tasks: readonly TaskState[];
+  /** Chronological log of tool invocations. */
+  readonly tools_used: readonly ToolContext[];
+  /** Agent or user preferences captured during the session. */
+  readonly preferences: Readonly<Record<string, string>>;
+  /** Optional compressed summary of the session's key content. */
+  readonly summary: string;
+  /** If this is a continuation, the ID of the preceding session. */
+  readonly parent_session_id: string | null;
+  /** Accumulated LLM API cost in USD for this session. */
+  readonly total_cost_usd: number;
+  /** ISO-8601 UTC timestamp of session creation. */
+  readonly created_at: string;
+  /** ISO-8601 UTC timestamp of last modification. */
+  readonly updated_at: string;
+  /** SHA-256 of the session's canonical JSON (excluding this field). */
+  readonly checksum: string;
+}
+
+// ---------------------------------------------------------------------------
+// API request types
+// ---------------------------------------------------------------------------
+
+/** Configuration for creating a new session. */
+export interface CreateSessionRequest {
+  /** Agent identifier that owns this session. */
+  readonly agent_id?: string;
+  /** Optional parent session to create a continuation from. */
+  readonly parent_session_id?: string;
+  /** Initial preference key-value pairs. */
+  readonly preferences?: Readonly<Record<string, string>>;
+}
+
+/** Request to resume a session using a resumption token. */
+export interface ResumeSessionRequest {
+  /** The opaque resumption token previously issued by the server. */
+  readonly resumption_token: string;
+}
+
+/** Request to save a serialised context payload. */
+export interface SaveContextRequest {
+  /** The session ID to update. */
+  readonly session_id: string;
+  /** Partial or full updated session state fields. */
+  readonly context: Partial<
+    Pick<SessionState, "segments" | "entities" | "tasks" | "tools_used" | "preferences" | "summary" | "total_cost_usd">
+  >;
+}
+
+// ---------------------------------------------------------------------------
+// Resumption token
+// ---------------------------------------------------------------------------
+
+/**
+ * An opaque token that enables resuming a serialised session across boundaries.
+ * Maps to the resumption token concept in agent_session_linker.portable.
+ */
+export interface ResumptionToken {
+  /** The token value to pass to resumeSession(). */
+  readonly token: string;
+  /** Session ID this token references. */
+  readonly session_id: string;
+  /** ISO-8601 UTC timestamp after which this token expires. */
+  readonly expires_at: string;
+  /** Schema version of the serialised payload. */
+  readonly schema_version: string;
+}
+
+// ---------------------------------------------------------------------------
+// Session list entry
+// ---------------------------------------------------------------------------
+
+/** Summary information returned when listing sessions. */
+export interface SessionSummary {
+  /** Unique session identifier. */
+  readonly session_id: string;
+  /** Agent that owns this session. */
+  readonly agent_id: string;
+  /** ISO-8601 UTC creation timestamp. */
+  readonly created_at: string;
+  /** ISO-8601 UTC last-update timestamp. */
+  readonly updated_at: string;
+  /** Total number of context segments. */
+  readonly segment_count: number;
+  /** Total number of tracked tasks. */
+  readonly task_count: number;
+  /** Whether this session has a parent (is a continuation). */
+  readonly is_continuation: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Session statistics
+// ---------------------------------------------------------------------------
+
+/** Aggregate statistics across all stored sessions. */
+export interface SessionStats {
+  /** Total number of stored sessions. */
+  readonly total_sessions: number;
+  /** Sum of all segment counts across sessions. */
+  readonly total_segments: number;
+  /** Sum of all token counts across sessions. */
+  readonly total_tokens: number;
+  /** Sum of all task counts across sessions. */
+  readonly total_tasks: number;
+  /** Sum of all entity counts across sessions. */
+  readonly total_entities: number;
+  /** Summed cost across all sessions in USD. */
+  readonly total_cost_usd: number;
+  /** List of unique agent IDs that have sessions. */
+  readonly agents: readonly string[];
+}
+
+// ---------------------------------------------------------------------------
+// API result wrapper
+// ---------------------------------------------------------------------------
+
+/** Standard error payload returned by the agent-session-linker API. */
+export interface ApiError {
+  readonly error: string;
+  readonly detail: string;
+}
+
+/** Result type for all client operations. */
+export type ApiResult<T> =
+  | { readonly ok: true; readonly data: T }
+  | { readonly ok: false; readonly error: ApiError; readonly status: number };

package/tsconfig.json

@@ -0,0 +1,25 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "lib": ["ES2020", "DOM"],
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "strict": true,
+    "noImplicitAny": true,
+    "strictNullChecks": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noImplicitReturns": true,
+    "exactOptionalPropertyTypes": true,
+    "forceConsistentCasingInFileNames": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}