@dexto/server 1.6.16 → 1.6.18

package/dist/hono/routes/sessions.js

@@ -1,12 +1,44 @@
 import { OpenAPIHono, createRoute, z } from "@hono/zod-openapi";
+import {
+  DextoRuntimeError,
+  ErrorScope,
+  ErrorType,
+  zodToIssues
+} from "@dexto/core";
 import {
   SessionMetadataSchema,
   InternalMessageSchema,
-  StandardErrorEnvelopeSchema
+  ScopedUsageSummarySchema,
+  StandardErrorEnvelopeSchema,
+  UsageSummarySchema
 } from "../schemas/responses.js";
+import { handleHonoError } from "../middleware/error.js";
 const CreateSessionSchema = z.object({
   sessionId: z.string().optional().describe("A custom ID for the new session")
 }).describe("Request body for creating a new session");
+const MAX_SYSTEM_PROMPT_CONTRIBUTOR_CONTENT_CHARS = 12e4;
+const DEFAULT_SYSTEM_PROMPT_CONTRIBUTOR_PRIORITY = 45;
+const SessionPromptContributorInfoSchema = z.object({
+  id: z.string().describe("Contributor identifier"),
+  priority: z.number().describe("Contributor priority")
+}).strict().describe("Session-scoped system prompt contributor metadata.");
+const UpsertSessionPromptContributorSchema = z.object({
+  id: z.string().min(1).describe("Contributor identifier"),
+  priority: z.number().int().nonnegative().optional().default(DEFAULT_SYSTEM_PROMPT_CONTRIBUTOR_PRIORITY).describe("Optional priority override"),
+  enabled: z.boolean().default(true).describe("Set false to remove the contributor instead of adding or updating it"),
+  content: z.string().optional().describe("Static contributor content for this session (required when enabled)")
+}).strict().superRefine((value, ctx) => {
+  if (value.enabled !== false && (!value.content || value.content.trim().length === 0)) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      path: ["content"],
+      message: "Contributor content is required when enabled"
+    });
+  }
+}).describe("Session-scoped system prompt contributor update payload.");
+function sanitizeContributorId(value) {
+  return value.trim().replace(/[^A-Za-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 80);
+}
 function mapSessionMetadata(sessionId, metadata, defaults) {
   return {
     id: sessionId,
@@ -14,12 +46,35 @@ function mapSessionMetadata(sessionId, metadata, defaults) {
     lastActivity: metadata?.lastActivity ?? defaults?.lastActivity ?? null,
     messageCount: metadata?.messageCount ?? defaults?.messageCount ?? 0,
     title: metadata?.title ?? defaults?.title ?? null,
+    ...metadata?.tokenUsage && { tokenUsage: metadata.tokenUsage },
+    ...metadata?.estimatedCost !== void 0 && {
+      estimatedCost: metadata.estimatedCost
+    },
+    ...metadata?.modelStats && { modelStats: metadata.modelStats },
+    ...metadata?.usageTracking && { usageTracking: metadata.usageTracking },
     workspaceId: metadata?.workspaceId ?? defaults?.workspaceId ?? null,
     parentSessionId: metadata?.parentSessionId ?? defaults?.parentSessionId ?? null
   };
 }
 function createSessionsRouter(getAgent) {
-  const app = new OpenAPIHono();
+  const app = new OpenAPIHono({
+    defaultHook: (result, ctx) => {
+      if (!result.success) {
+        const issues = zodToIssues(result.error);
+        return handleHonoError(
+          ctx,
+          new DextoRuntimeError(
+            "validation_failed",
+            "validation",
+            ErrorType.USER,
+            issues[0]?.message ?? "Validation failed",
+            { issues }
+          )
+        );
+      }
+    }
+  });
+  app.onError((err, ctx) => handleHonoError(ctx, err));
   const listRoute = createRoute({
     method: "get",
     path: "/sessions",
@@ -148,6 +203,86 @@ function createSessionsRouter(getAgent) {
       }
     }
   });
+  const listSessionPromptContributorsRoute = createRoute({
+    method: "get",
+    path: "/sessions/{sessionId}/system-prompt/contributors",
+    summary: "List Session System Prompt Contributors",
+    description: "Lists static system prompt contributors that apply only to the specified session.",
+    tags: ["sessions", "config"],
+    request: { params: z.object({ sessionId: z.string().describe("Session identifier") }) },
+    responses: {
+      200: {
+        description: "Current session contributor list",
+        content: {
+          "application/json": {
+            schema: z.object({
+              contributors: z.array(SessionPromptContributorInfoSchema).describe("Registered session prompt contributors.")
+            }).strict()
+          }
+        }
+      },
+      404: {
+        description: "Session not found",
+        content: {
+          "application/json": {
+            schema: StandardErrorEnvelopeSchema
+          }
+        }
+      }
+    }
+  });
+  const upsertSessionPromptContributorRoute = createRoute({
+    method: "post",
+    path: "/sessions/{sessionId}/system-prompt/contributors",
+    summary: "Upsert Session System Prompt Contributor",
+    description: "Adds or updates a static system prompt contributor that applies only to the specified session. Set enabled=false to remove it.",
+    tags: ["sessions", "config"],
+    request: {
+      params: z.object({ sessionId: z.string().describe("Session identifier") }),
+      body: {
+        required: true,
+        content: {
+          "application/json": {
+            schema: UpsertSessionPromptContributorSchema
+          }
+        }
+      }
+    },
+    responses: {
+      200: {
+        description: "Session contributor upsert result",
+        content: {
+          "application/json": {
+            schema: z.object({
+              id: z.string().describe("Contributor identifier"),
+              enabled: z.boolean().describe("Whether the contributor remains enabled"),
+              priority: z.number().optional().describe("Contributor priority"),
+              replaced: z.boolean().optional().describe("Whether an existing contributor was replaced"),
+              removed: z.boolean().optional().describe("Whether the contributor was removed"),
+              contentLength: z.number().optional().describe("Stored content length in characters"),
+              truncated: z.boolean().optional().describe("Whether the submitted content was truncated")
+            }).strict()
+          }
+        }
+      },
+      400: {
+        description: "Invalid session contributor request",
+        content: {
+          "application/json": {
+            schema: StandardErrorEnvelopeSchema
+          }
+        }
+      },
+      404: {
+        description: "Session not found",
+        content: {
+          "application/json": {
+            schema: StandardErrorEnvelopeSchema
+          }
+        }
+      }
+    }
+  });
   const deleteRoute = createRoute({
     method: "delete",
     path: "/sessions/{sessionId}",
@@ -226,6 +361,15 @@ function createSessionsRouter(getAgent) {
               session: SessionMetadataSchema.extend({
                 isBusy: z.boolean().describe(
                   "Whether the session is currently processing a message"
+                ),
+                usageSummary: UsageSummarySchema.describe(
+                  "Exact usage summary derived from assistant message history"
+                ),
+                activeUsageScopeId: z.string().nullable().describe(
+                  "Current runtime usage scope identifier, if configured"
+                ),
+                activeUsageScope: ScopedUsageSummarySchema.nullable().describe(
+                  "Usage summary for the current runtime scope, if configured"
                 )
               }).describe("Session metadata with processing status")
             }).strict()
@@ -244,6 +388,29 @@ function createSessionsRouter(getAgent) {
       }
     }
   });
+  const clearContextRoute = createRoute({
+    method: "post",
+    path: "/sessions/{sessionId}/clear-context",
+    summary: "Clear Session Context",
+    description: "Clears the model context window for a session while preserving conversation history for review.",
+    tags: ["sessions"],
+    request: {
+      params: z.object({ sessionId: z.string().describe("Session identifier") })
+    },
+    responses: {
+      200: {
+        description: "Session context cleared successfully",
+        content: {
+          "application/json": {
+            schema: z.object({
+              status: z.literal("context cleared").describe("Context clear status"),
+              sessionId: z.string().describe("Session ID")
+            }).strict()
+          }
+        }
+      }
+    }
+  });
   const patchRoute = createRoute({
     method: "patch",
     path: "/sessions/{sessionId}",
@@ -362,6 +529,81 @@ function createSessionsRouter(getAgent) {
       history,
       isBusy
     });
+  }).openapi(listSessionPromptContributorsRoute, async (ctx) => {
+    const agent = await getAgent(ctx);
+    const { sessionId } = ctx.req.valid("param");
+    const contributors = await agent.getSessionSystemPromptContributors(sessionId);
+    return ctx.json(
+      {
+        contributors: contributors.map((contributor) => ({
+          id: contributor.id,
+          priority: contributor.priority
+        }))
+      },
+      200
+    );
+  }).openapi(upsertSessionPromptContributorRoute, async (ctx) => {
+    const agent = await getAgent(ctx);
+    const { sessionId } = ctx.req.valid("param");
+    const payload = ctx.req.valid("json");
+    const contributorId = sanitizeContributorId(payload.id);
+    if (contributorId.length === 0) {
+      throw new DextoRuntimeError(
+        "session_systemprompt_contributor_config_invalid",
+        ErrorScope.SYSTEM_PROMPT,
+        ErrorType.USER,
+        "A valid contributor id is required",
+        {
+          id: payload.id,
+          sessionId
+        }
+      );
+    }
+    const rawContent = payload.content ?? "";
+    const content = rawContent.slice(0, MAX_SYSTEM_PROMPT_CONTRIBUTOR_CONTENT_CHARS);
+    if (!payload.enabled) {
+      const removed = await agent.removeSessionSystemPromptContributor(
+        sessionId,
+        contributorId
+      );
+      return ctx.json(
+        {
+          id: contributorId,
+          enabled: false,
+          removed
+        },
+        200
+      );
+    }
+    if (content.trim().length === 0) {
+      throw new DextoRuntimeError(
+        "session_systemprompt_contributor_config_invalid",
+        ErrorScope.SYSTEM_PROMPT,
+        ErrorType.USER,
+        "Contributor content is required when enabled",
+        {
+          id: payload.id,
+          sessionId
+        }
+      );
+    }
+    const priority = payload.priority;
+    const result = await agent.upsertSessionSystemPromptContributor(sessionId, {
+      id: contributorId,
+      priority,
+      content
+    });
+    return ctx.json(
+      {
+        id: contributorId,
+        enabled: true,
+        priority,
+        replaced: result.replaced,
+        contentLength: content.length,
+        truncated: rawContent.length > content.length
+      },
+      200
+    );
   }).openapi(deleteRoute, async (ctx) => {
     const agent = await getAgent(ctx);
     const { sessionId } = ctx.req.param();
@@ -405,15 +647,29 @@ function createSessionsRouter(getAgent) {
     }
     const metadata = await agent.getSessionMetadata(sessionId);
     const isBusy = await agent.isSessionBusy(sessionId);
+    const usageSummary = await agent.getSessionUsageSummary(sessionId);
+    const activeUsageScopeId = agent.getEffectiveConfig().usageScopeId ?? null;
+    const activeUsageScope = activeUsageScopeId ? {
+      scopeId: activeUsageScopeId,
+      ...await agent.getSessionUsageSummary(sessionId, activeUsageScopeId)
+    } : null;
     return ctx.json(
       {
         session: {
           ...mapSessionMetadata(sessionId, metadata),
-          isBusy
+          isBusy,
+          usageSummary,
+          activeUsageScopeId,
+          activeUsageScope
         }
       },
       200
     );
+  }).openapi(clearContextRoute, async (ctx) => {
+    const agent = await getAgent(ctx);
+    const { sessionId } = ctx.req.valid("param");
+    await agent.clearContext(sessionId);
+    return ctx.json({ status: "context cleared", sessionId });
   }).openapi(patchRoute, async (ctx) => {
     const agent = await getAgent(ctx);
     const { sessionId } = ctx.req.valid("param");

package/dist/hono/routes/system-prompt.d.ts

@@ -42,9 +42,9 @@ export declare function createSystemPromptRouter(getAgent: GetAgentFn): OpenAPIH
             output: {
                 id: string;
                 enabled: boolean;
-                removed?: boolean | undefined;
                 priority?: number | undefined;
                 replaced?: boolean | undefined;
+                removed?: boolean | undefined;
                 contentLength?: number | undefined;
                 truncated?: boolean | undefined;
             };

package/dist/hono/schemas/responses.cjs

@@ -39,6 +39,7 @@ __export(responses_exports, {
   ModelStatisticsSchema: () => ModelStatisticsSchema,
   OkResponseSchema: () => OkResponseSchema,
   PermissionsConfigSchema: () => import_core6.PermissionsConfigSchema,
+  PricingStatusSchema: () => PricingStatusSchema,
   PromptArgumentSchema: () => PromptArgumentSchema,
   PromptDefinitionSchema: () => PromptDefinitionSchema,
   PromptInfoSchema: () => PromptInfoSchema,
@@ -48,11 +49,13 @@ __export(responses_exports, {
   ResourceSchema: () => ResourceSchema,
   ScheduleSchema: () => ScheduleSchema,
   ScheduleTaskSchema: () => ScheduleTaskSchema,
+  ScopedUsageSummarySchema: () => ScopedUsageSummarySchema,
   SearchResultSchema: () => SearchResultSchema,
   SessionMetadataSchema: () => SessionMetadataSchema,
   SessionSearchResponseSchema: () => SessionSearchResponseSchema,
   SessionSearchResultSchema: () => SessionSearchResultSchema,
   SessionTokenUsageSchema: () => SessionTokenUsageSchema,
+  SessionUsageTrackingSchema: () => SessionUsageTrackingSchema,
   SseServerConfigSchema: () => import_core5.SseServerConfigSchema,
   StandardErrorEnvelopeSchema: () => StandardErrorEnvelopeSchema,
   StatusResponseSchema: () => StatusResponseSchema,
@@ -62,6 +65,7 @@ __export(responses_exports, {
   ToolCallSchema: () => ToolCallSchema,
   ToolSchema: () => ToolSchema,
   UIResourcePartSchema: () => UIResourcePartSchema,
+  UsageSummarySchema: () => UsageSummarySchema,
   WebhookSchema: () => WebhookSchema,
   WorkspaceSchema: () => WorkspaceSchema
 });
@@ -121,8 +125,11 @@ const TokenUsageSchema = import_zod.z.object({
   inputTokens: import_zod.z.number().int().nonnegative().optional().describe("Number of input tokens"),
   outputTokens: import_zod.z.number().int().nonnegative().optional().describe("Number of output tokens"),
   reasoningTokens: import_zod.z.number().int().nonnegative().optional().describe("Number of reasoning tokens"),
+  cacheReadTokens: import_zod.z.number().int().nonnegative().optional().describe("Number of cache read tokens"),
+  cacheWriteTokens: import_zod.z.number().int().nonnegative().optional().describe("Number of cache write tokens"),
   totalTokens: import_zod.z.number().int().nonnegative().optional().describe("Total tokens used")
 }).strict().describe("Token usage accounting");
+const PricingStatusSchema = import_zod.z.enum(import_core.LLM_PRICING_STATUSES).describe("Whether pricing was resolved for this response");
 const InternalMessageSchema = import_zod.z.object({
   id: import_zod.z.string().uuid().optional().describe("Unique message identifier (UUID)"),
   role: import_zod.z.enum(["system", "user", "assistant", "tool"]).describe("Role of the message sender"),
@@ -130,6 +137,11 @@ const InternalMessageSchema = import_zod.z.object({
   content: import_zod.z.union([import_zod.z.string(), import_zod.z.null(), import_zod.z.array(ContentPartSchema)]).describe("Message content (string, null, or array of parts)"),
   reasoning: import_zod.z.string().optional().describe("Optional model reasoning text"),
   tokenUsage: TokenUsageSchema.optional().describe("Optional token usage accounting"),
+  estimatedCost: import_zod.z.number().nonnegative().optional().describe("Estimated cost in USD for this response"),
+  pricingStatus: PricingStatusSchema.optional().describe(
+    "Whether pricing was resolved for this response"
+  ),
+  usageScopeId: import_zod.z.string().optional().describe("Optional usage scope identifier for runtime-scoped metering"),
   model: import_zod.z.string().optional().describe("Model identifier for assistant messages"),
   provider: import_zod.z.enum(import_core.LLM_PROVIDERS).optional().describe("Provider identifier for assistant messages"),
   toolCalls: import_zod.z.array(ToolCallSchema).optional().describe("Tool calls made by the assistant"),
@@ -141,14 +153,12 @@ const LLMConfigResponseSchema = import_core.LLMConfigBaseSchema.omit({ apiKey: t
   hasApiKey: import_zod.z.boolean().optional().describe("Whether an API key is configured")
 }).describe("LLM configuration (apiKey omitted for security)");
 const LLMConfigSchema = import_core.LLMConfigBaseSchema.describe("LLM configuration with API key");
-const SessionTokenUsageSchema = import_zod.z.object({
-  inputTokens: import_zod.z.number().int().nonnegative().describe("Number of input tokens"),
-  outputTokens: import_zod.z.number().int().nonnegative().describe("Number of output tokens"),
-  reasoningTokens: import_zod.z.number().int().nonnegative().describe("Number of reasoning tokens"),
-  cacheReadTokens: import_zod.z.number().int().nonnegative().describe("Number of cache read tokens"),
-  cacheWriteTokens: import_zod.z.number().int().nonnegative().describe("Number of cache write tokens"),
-  totalTokens: import_zod.z.number().int().nonnegative().describe("Total tokens used")
-}).strict().describe("Session-level token usage (all fields required for cumulative totals)");
+const SessionTokenUsageSchema = TokenUsageSchema.required().describe(
+  "Session-level token usage (all fields required for cumulative totals)"
+);
+const SessionUsageTrackingSchema = import_zod.z.object({
+  hasUntrackedChatGPTLoginUsage: import_zod.z.boolean().optional().describe("Whether this session includes known untracked ChatGPT Login usage")
+}).strict().describe("Usage tracking caveats for a session");
 const ModelStatisticsSchema = import_zod.z.object({
   provider: import_zod.z.string().describe("LLM provider identifier"),
   model: import_zod.z.string().describe("Model identifier"),
@@ -158,6 +168,29 @@ const ModelStatisticsSchema = import_zod.z.object({
   firstUsedAt: import_zod.z.number().int().positive().describe("First use timestamp (Unix ms)"),
   lastUsedAt: import_zod.z.number().int().positive().describe("Last use timestamp (Unix ms)")
 }).strict().describe("Per-model statistics within a session");
+const UsageSummarySchema = import_zod.z.object({
+  tokenUsage: SessionTokenUsageSchema.describe(
+    "Aggregate token usage for the selected scope"
+  ),
+  estimatedCost: import_zod.z.number().nonnegative().describe("Total estimated cost in USD for the selected scope"),
+  hasUnpricedResponses: import_zod.z.boolean().describe(
+    "Whether any response in the selected scope has usage but no resolved pricing"
+  ),
+  modelStats: import_zod.z.array(
+    import_zod.z.object({
+      provider: import_zod.z.string().describe("LLM provider identifier"),
+      model: import_zod.z.string().describe("Model identifier"),
+      messageCount: import_zod.z.number().int().nonnegative().describe("Number of responses using this model in the selected scope"),
+      tokenUsage: SessionTokenUsageSchema.describe(
+        "Token usage for this model in the selected scope"
+      ),
+      estimatedCost: import_zod.z.number().nonnegative().describe("Estimated cost in USD for this model in the selected scope")
+    }).strict()
+  ).optional().describe("Per-model usage statistics within the selected scope")
+}).strict().describe("Usage summary for a session or session scope");
+const ScopedUsageSummarySchema = UsageSummarySchema.extend({
+  scopeId: import_zod.z.string().describe("Usage scope identifier")
+}).strict().describe("Usage summary for a specific scope within a session");
 const SessionMetadataSchema = import_zod.z.object({
   id: import_zod.z.string().describe("Unique session identifier"),
   createdAt: import_zod.z.number().int().positive().nullable().describe("Creation timestamp (Unix ms, null if unavailable)"),
@@ -169,6 +202,9 @@ const SessionMetadataSchema = import_zod.z.object({
   ),
   estimatedCost: import_zod.z.number().nonnegative().optional().describe("Total estimated cost in USD across all models"),
   modelStats: import_zod.z.array(ModelStatisticsSchema).optional().describe("Per-model usage statistics (for multi-model sessions)"),
+  usageTracking: SessionUsageTrackingSchema.optional().describe(
+    "Known caveats or gaps in usage tracking for this session"
+  ),
   workspaceId: import_zod.z.string().optional().nullable().describe("Associated workspace ID, if any"),
   parentSessionId: import_zod.z.string().optional().nullable().describe("Parent session ID if this session was forked, otherwise null")
 }).strict().describe("Session metadata");
@@ -379,6 +415,7 @@ const DeleteResponseSchema = import_zod.z.object({
   ModelStatisticsSchema,
   OkResponseSchema,
   PermissionsConfigSchema,
+  PricingStatusSchema,
   PromptArgumentSchema,
   PromptDefinitionSchema,
   PromptInfoSchema,
@@ -388,11 +425,13 @@ const DeleteResponseSchema = import_zod.z.object({
   ResourceSchema,
   ScheduleSchema,
   ScheduleTaskSchema,
+  ScopedUsageSummarySchema,
   SearchResultSchema,
   SessionMetadataSchema,
   SessionSearchResponseSchema,
   SessionSearchResultSchema,
   SessionTokenUsageSchema,
+  SessionUsageTrackingSchema,
   SseServerConfigSchema,
   StandardErrorEnvelopeSchema,
   StatusResponseSchema,
@@ -402,6 +441,7 @@ const DeleteResponseSchema = import_zod.z.object({
   ToolCallSchema,
   ToolSchema,
   UIResourcePartSchema,
+  UsageSummarySchema,
   WebhookSchema,
   WorkspaceSchema
 });