@asterism-app/sdk 0.0.0-stage → 1.0.0

package/src/runtime-sessions.ts

@@ -0,0 +1,36 @@
+import type { Json } from "./json.ts";
+import type { ActionContract, CreationContract } from "./commands.ts";
+import type { ResourceContract } from "./module-contract.ts";
+import type { ContentReader } from "./content-runtime.ts";
+import type { ObjectReader, ObjectWriter, SessionReader } from "./objects.ts";
+import type { ResourceCreationResult } from "./workspace.ts";
+
+declare const prepared: unique symbol;
+/** Host-issued resource preparation, valid only within one session creation attempt. */
+export interface PreparedCreation { readonly [prepared]: true }
+export interface SessionPreparation {
+  readonly signal: AbortSignal;
+  prepare<I, S extends Json, O extends Json>(contract: CreationContract<I, S, O>, input: NoInfer<I> & Json): Promise<PreparedCreation>;
+  /** Run action parsing and registered preparers for a resource awaiting initialization; this does not execute the action. */
+  prepareAction<I, O extends Json>(resource: PreparedCreation, contract: ActionContract<I, O>, input: NoInfer<I> & Json): Promise<O>;
+}
+export interface ObjectInitializer extends ObjectReader {
+  commit(work: (writer: ObjectWriter) => undefined): void;
+}
+export interface SessionInitializer extends SessionReader {
+  /** Materialize each prepared resource once, preserving its preparation identity. */
+  create(prepared: PreparedCreation): ResourceCreationResult;
+  object<S extends Json>(contract: ResourceContract<S>, id: string): ObjectInitializer;
+}
+export interface SessionInitialization {
+  title: string;
+  /** Synchronous initialization commits session identity, resources, and initial records together. */
+  initialize(session: SessionInitializer): undefined;
+}
+export interface SessionCreation {
+  /** The key identifies one accepted creation within this plugin; retries return its existing session. */
+  (key: string, prepare: (context: SessionPreparation) => Promise<SessionInitialization>, options?: {
+    signal?: AbortSignal;
+    content?: ContentReader;
+  }): Promise<string>;
+}

package/src/runtime-shell.ts

@@ -0,0 +1,18 @@
+import type { Json } from "./json.ts";
+import type { CallResult } from "./runtime-contracts.ts";
+import type { ExecResult, ShellSettings, ShellProfileList } from "./shell.ts";
+import type { TerminalSessions } from "./runtime-terminal.ts";
+
+export interface ShellProfiles { get(): ShellSettings; list(): Promise<ShellProfileList> }
+/** One noninteractive shell command with piped output and its own process lifetime. */
+export interface ShellExecution {
+  inspect(): Promise<Json>;
+  execute(cwd: string, args: { command: string; timeout?: number }, options: {
+    signal: AbortSignal; publish(data: ExecResult): void;
+  }): Promise<CallResult<ExecResult>>;
+}
+/** Host shell capabilities share configured profiles; plugins own how they compose commands and terminal sessions. */
+export interface ShellServices extends ShellExecution {
+  readonly profiles: ShellProfiles;
+  readonly terminals: TerminalSessions;
+}

package/src/runtime-terminal.ts

@@ -0,0 +1,24 @@
+import type { TerminalConfig, TerminalDown, TerminalUp, TerminalStatus, TerminalImage } from "./terminal.ts";
+
+export interface TerminalViewer { send(frame: TerminalDown): void }
+export class TerminalError extends Error { constructor(readonly code: string, message: string) { super(message); } }
+export interface InteractiveTerminal {
+  readonly status: TerminalStatus;
+  readonly started: boolean;
+  readonly applicationCursor: boolean;
+  start(): Promise<void>;
+  close(): Promise<void>;
+  dispose(): Promise<void>;
+  attach(viewer: TerminalViewer): (message: TerminalUp) => void;
+  detach(viewer: TerminalViewer): void;
+  input(data: string, signal: AbortSignal): Promise<TerminalStatus>;
+  read(source: "screen" | "history" | "raw", offset?: number, limit?: number): Promise<TerminalStatus & {
+    source: "screen" | "history" | "raw"; text: string; cols: number; rows: number;
+    cursor: { x: number; y: number }; offset: number; nextOffset: number; truncated: boolean;
+  }>;
+  image(): Promise<TerminalImage>;
+  waitIdle(timeout: number, signal: AbortSignal): Promise<TerminalStatus & { reason: string; elapsedMs: number }>;
+}
+export interface TerminalSessions {
+  create(config: TerminalConfig, events: { failed(error: unknown): void; log(message: string, error: unknown): void }): InteractiveTerminal;
+}

package/src/runtime-tools.ts

@@ -0,0 +1,31 @@
+import { defineTool, type ToolContract } from "./module-contract.ts";
+import type { Json } from "./json.ts";
+import type { ObjectReader, ToolSession } from "./objects.ts";
+import type { CallResult } from "./runtime-contracts.ts";
+import type { ToolModelOutput } from "./tool-result.ts";
+import type { z } from "zod";
+
+export interface TopLevelToolContext<D extends Json = Json> {
+  readonly object: ObjectReader;
+  readonly session: ToolSession;
+  readonly callId: string;
+  readonly signal: AbortSignal;
+  publish(data: D): void;
+}
+/** Top-level tools declare their definition and implementation together, independently of resource support relationships. */
+export interface TopLevelTool<A extends Json = Json, D extends Json = Json> extends ToolContract<A> {
+  /** Encodes D for progress/history and decodes it for views and model projection. */
+  readonly resultSchema: z.ZodType<D>;
+  readonly effect: "read" | "write";
+  readonly execution: "parallel" | "sequential";
+  execute(args: A, context: TopLevelToolContext<D>): Promise<CallResult<D>>;
+  toModel?(data: D): ToolModelOutput;
+}
+export function defineTopLevelTool<A extends Json, D extends Json>(definition: TopLevelTool<A, D>): TopLevelTool {
+  if (!definition.resultSchema.description?.trim()) throw new Error(`Missing result schema description: ${definition.id}`);
+  const tool = defineTool(definition);
+  return { ...definition, ...tool,
+    execute: (args, context) => definition.execute(args as A, context as TopLevelToolContext<D>),
+    ...(definition.toModel ? { toModel: (data: Json) => definition.toModel!(data as D) } : {}),
+  } as TopLevelTool;
+}

package/src/runtime-usage.ts

@@ -0,0 +1,54 @@
+import type { ProviderUsageError, UsageItem, UsageProviderInfo } from "./provider-usage.ts";
+import type { UiText } from "./i18n.ts";
+import type { ProviderUsageState } from "./usage-state.ts";
+import type { ModelResponse } from "./models.ts";
+
+/** Consumers explicitly supply the connection and credentials required for the query. */
+export interface UsageQueryContext {
+  readonly connection: { id: string; endpoint: string };
+  readonly credential: string | null;
+  readonly signal: AbortSignal;
+}
+interface UsageProviderIdentity {
+  readonly id: string;
+  readonly label: UiText;
+}
+export interface QueryUsageProvider extends UsageProviderIdentity {
+  readonly source?: "query";
+  query(context: UsageQueryContext): Promise<UsageItem[]>;
+}
+export interface UsageHeadersContext {
+  readonly connection: { id: string; endpoint: string };
+  readonly model: string;
+  readonly status: number;
+  readonly receivedAt: number;
+  readonly headers: Readonly<Record<string, string>>;
+}
+/** Consumers supply response metadata they obtained themselves; the parser makes no network requests. */
+export interface HeadersUsageProvider extends UsageProviderIdentity {
+  readonly source: "headers";
+  /** null means no usable data this time; an empty list explicitly reports no quota items. */
+  parseHeaders(context: UsageHeadersContext): UsageItem[] | null;
+}
+export type UsageProvider = QueryUsageProvider | HeadersUsageProvider;
+/** Providers report publicly exposable error categories; raw responses and credentials are not delivered across processes. */
+export class UsageQueryError extends Error {
+  constructor(readonly code: ProviderUsageError) { super(`Provider usage query failed: ${code}.`); }
+}
+export interface UsageProviderServices {
+  list(): readonly UsageProviderInfo[];
+  /** Obtain an implementation bound to the provider lifecycle; does not select connections, read credentials, or save results. */
+  get(id: string): UsageProvider | null;
+  subscribe(listener: () => void): () => void;
+}
+/** Stateless invocation facade; consumers explicitly supply connections, credentials, and responses. */
+export interface UsageServices {
+  query(providerId: string, context: UsageQueryContext): Promise<UsageItem[]>;
+  parseHeaders(providerId: string, context: UsageHeadersContext): UsageItem[] | null;
+}
+
+/** Host cache and shared queries; consumers supply response headers they obtained themselves. */
+export interface ProviderUsage {
+  query(id: string, options?: { signal?: AbortSignal; refresh?: boolean }): Promise<ProviderUsageState>;
+  consume(response: ModelResponse): void;
+}

package/src/runtime-web.ts

@@ -0,0 +1,36 @@
+import type { UiText } from "./i18n.ts";
+import type { WebCredentialDefinition, WebProviderState, WebProviderType, WebSearchRequest, WebFetchRequest, WebResponse, WebSearchResult, WebFetchResult } from "./web.ts";
+
+export interface WebProviderInstance {
+  search?(request: WebSearchRequest, options: { signal: AbortSignal }): Promise<WebResponse>;
+  fetch?(request: WebFetchRequest, options: { signal: AbortSignal }): Promise<WebResponse>;
+}
+export interface WebProviderDefinition {
+  id: string;
+  label: UiText;
+  search: boolean;
+  fetch: boolean;
+  /** Glob for the complete URL, with * matching any characters; fetch routing matches in declaration order. */
+  urlPatterns: readonly string[];
+  defaultBaseUrl: string;
+  /** Required credential type; null means no credentials are required. */
+  credential: WebCredentialDefinition | null;
+  /** Synchronous factory; baseUrl has trailing slashes removed, and credential is null if and only if the credential declaration is null. */
+  create(context: { baseUrl: string; credential: string | null }): WebProviderInstance;
+}
+export interface WebProviderServices {
+  types(): readonly WebProviderType[];
+  list(): readonly WebProviderState[];
+  get(id: string): WebProviderState | null;
+  /** Return an invocation facade bound to the provider lifecycle; id is the provider type slug. */
+  resolve(id: string, options: { signal: AbortSignal }): Promise<WebProviderInstance>;
+  subscribe(listener: () => void): () => void;
+}
+export interface WebServices {
+  search(request: WebSearchRequest, options: { signal: AbortSignal }): Promise<WebSearchResult>;
+  fetch(request: WebFetchRequest, options: { signal: AbortSignal }): Promise<WebFetchResult>;
+}
+export type WebErrorCode = "provider_unavailable" | "credential_unavailable" | "unsupported" | "invalid_request" | "protocol" | "request_failed";
+export class WebError extends Error {
+  constructor(readonly code: WebErrorCode, message: string) { super(message); }
+}

package/src/runtime.ts

@@ -0,0 +1,53 @@
+/** SDK runtime entry point: generic service interfaces available to backend plugins; excludes host internal types and domain knowledge. */
+import type { Json } from "./json.ts";
+import type { UiText } from "./i18n.ts";
+import type { ResourceRef } from "./workspace.ts";
+export * from "./runtime-contracts.ts";
+export * from "./runtime-resources.ts";
+export * from "./runtime-calls.ts";
+export * from "./runtime-channels.ts";
+export * from "./runtime-tools.ts";
+export type * from "./runtime-model-providers.ts";
+export * from "./runtime-usage.ts";
+export * from "./runtime-web.ts";
+export * from "./runtime-agent-catalog.ts";
+export * from "./runtime-sessions.ts";
+export type * from "./content-runtime.ts";
+export type * from "./models.ts";
+export { validationMessage, jsonArgumentHint } from "./tool-validation.ts";
+
+/** Stable plugin API error: code supports plugin branching, and message is used for logs. */
+export class PluginApiError extends Error {
+  constructor(readonly code: "invalid_argument" | "foreign_resource" | "foreign_event" | "unavailable" | "rejected" | "conflict" | "not_found", message: string,
+    /** Business reason codes for preparation rejection or model input preflight checks. */
+    readonly reason?: string, readonly display?: UiText) { super(message); }
+}
+export interface PluginLogger {
+  info(message: string): void;
+  warn(message: string): void;
+  error(message: string, error?: unknown): void;
+}
+/** Backend handle for host-managed configuration: get reads the current value each time; update uses the latest complete configuration; subscribe receives changes from settings pages or other modules. */
+export interface PluginConfig<T extends Json> {
+  get(): T;
+  update(next: (current: T) => T): void;
+  subscribe(listener: (value: T) => void): () => void;
+}
+/** Namespaced credentials: plaintext exists only in the system-protected vault, while plugin directories store only references. */
+export interface PluginSecrets {
+  get(key: string): Promise<string | null>;
+  set(key: string, value: string): Promise<void>;
+  delete(key: string): Promise<void>;
+}
+/** Host-managed asynchronous tasks within the process: a running key is not started again, and host shutdown cancels tasks; no timeout by default, and tasks are not resumed after restart. */
+export interface PluginTasks {
+  start(key: string, run: (signal: AbortSignal) => Promise<void>, options?: { timeoutMs?: number; object?: ResourceRef }): boolean;
+  cancel(key: string): void;
+  has(key: string): boolean;
+}
+
+export type * from "./runtime-application.ts";
+
+export * from "./runtime-shell.ts";
+export * from "./runtime-terminal.ts";
+export type * from "./runtime-mcp.ts";

package/src/session-title.ts

@@ -0,0 +1,8 @@
+import { z } from "zod";
+import { defineRecord } from "./records.ts";
+import { presentationSchema } from "./presentation.ts";
+
+/** Immutable title assignment; optional detail belongs to the plugin that produced it. */
+export const SessionTitleAssigned = defineRecord("asterism.session/title", {
+  schema: z.strictObject({ title: z.string().trim().min(1).max(160), detail: presentationSchema.optional() }),
+});

package/src/shell.ts

@@ -0,0 +1,76 @@
+import { z } from "zod";
+import { defineCall } from "./calls.ts";
+import { defineData } from "./presentation.ts";
+
+export const OUTPUT_CHAR_LIMIT = 16_384;
+export const MAX_TIMEOUT_SECONDS = 2_147_483_647 / 1000;
+
+/** Startup arguments and command arguments are separate, allowing a profile to be shared across different shell usage modes. */
+export const shellProfileSchema = z.strictObject({
+  id: z.string().trim().min(1).max(160).regex(/^[a-z0-9]+(?:[-_][a-z0-9]+)*$/u).refine(value => value !== "auto", "The profile ID 'auto' is reserved."),
+  executable: z.string().trim().min(1),
+  args: z.array(z.string()),
+  commandArgs: z.array(z.string()),
+  env: z.record(z.string(), z.string()),
+});
+export type ShellProfile = z.infer<typeof shellProfileSchema>;
+
+export const shellPresets: ShellProfile[] = [
+  { id: "pwsh", executable: "pwsh", args: [], commandArgs: ["-NonInteractive", "-Command"], env: {} },
+  { id: "nu", executable: "nu", args: ["-l"], commandArgs: ["-c"], env: {} },
+  { id: "fish", executable: "fish", args: [], commandArgs: ["-c"], env: {} },
+  { id: "zsh", executable: "zsh", args: [], commandArgs: ["-c"], env: {} },
+  { id: "bash", executable: "bash", args: [], commandArgs: ["-c"], env: {} },
+  { id: "sh", executable: "sh", args: [], commandArgs: ["-c"], env: {} },
+];
+export const defaultShellSettings = { selected: "auto", profiles: shellPresets };
+export const shellSettingsSchema = z.strictObject({
+  selected: z.string().min(1),
+  profiles: z.array(shellProfileSchema),
+}).superRefine((value, ctx) => {
+  const ids = new Set<string>();
+  value.profiles.forEach((profile, index) => {
+    if (ids.has(profile.id)) ctx.addIssue({ code: "custom", path: ["profiles", index, "id"], message: "Shell profile IDs must be unique." });
+    ids.add(profile.id);
+  });
+  if (value.selected !== "auto" && !ids.has(value.selected))
+    ctx.addIssue({ code: "custom", path: ["selected"], message: "Select an existing shell profile or auto." });
+});
+export type ShellSettings = z.infer<typeof shellSettingsSchema>;
+export const ShellProfilesCatalog = defineData("asterism.shell/profiles", shellSettingsSchema);
+
+export const shellProfileListSchema = z.strictObject({
+  selected: z.string(),
+  resolvedProfile: z.string().nullable(),
+  profiles: z.array(z.strictObject({
+    id: z.string(),
+    executable: z.string(),
+    args: z.array(z.string()),
+    commandArgs: z.array(z.string()),
+    available: z.boolean(),
+    resolvedExecutable: z.string().nullable(),
+  })),
+});
+export type ShellProfileList = z.infer<typeof shellProfileListSchema>;
+
+export const shellOutputSchema = z.strictObject({
+  output: z.string(),
+  truncation: z.strictObject({
+    totalChars: z.number().int().nonnegative(),
+    retainedChars: z.number().int().nonnegative(),
+    file: z.string(),
+  }).nullable(),
+});
+export type ShellOutput = z.infer<typeof shellOutputSchema>;
+export const execResultSchema = shellOutputSchema.extend({
+  shell: z.string(),
+  termination: z.enum(["running", "exited", "timeout", "cancelled", "spawn_error", "io_error"]),
+  exitCode: z.number().int().nullable(),
+  signal: z.string().nullable(),
+  durationMs: z.number().nonnegative(),
+});
+export type ExecResult = z.infer<typeof execResultSchema>;
+
+export const ReadShellProfiles = defineCall("core.shell.profiles.read", {
+  scope: "plugin", input: z.strictObject({}), output: shellProfileListSchema,
+});

package/src/terminal.ts

@@ -0,0 +1,36 @@
+import { z } from "zod";
+
+export const terminalStateSchema = z.enum(["inactive", "starting", "idle", "running", "unknown", "exited", "failed"]);
+export type TerminalState = z.infer<typeof terminalStateSchema>;
+export const terminalConfigSchema = z.strictObject({ cwd: z.string(), profile: z.string() });
+export type TerminalConfig = z.infer<typeof terminalConfigSchema>;
+
+export const terminalStatusSchema = z.strictObject({
+  state: terminalStateSchema, shell: z.string().nullable(), integration: z.boolean(),
+  exitCode: z.number().nullable(), error: z.string().nullable(),
+  /** Current directory reported by shell integration; null without integration. */
+  cwd: z.string().nullable(),
+  /** Exit code of the latest foreground command; null without integration or before any command has run. */
+  lastExitCode: z.number().nullable(),
+});
+export type TerminalStatus = z.infer<typeof terminalStatusSchema>;
+export const inactiveStatus: TerminalStatus = { state: "inactive", shell: null, integration: false, exitCode: null, error: null, cwd: null, lastExitCode: null };
+
+/** Terminal channel: the frontend sends input, dimensions, and rendered-character acknowledgments; the backend sends screen resets, output, dimensions, and status, all delivered in order. */
+export type TerminalUp =
+  | { type: "input"; data: string }
+  /** xterm binary input (such as X10 mouse reports), with each character representing one byte. */
+  | { type: "binary"; data: string }
+  | { type: "resize"; cols: number; rows: number }
+  | { type: "ack"; chars: number }
+  /** The frontend screen has remounted and requests a current screen snapshot. */
+  | { type: "refresh" };
+export type TerminalDown =
+  | { type: "reset"; cols: number; rows: number; data: string }
+  | { type: "output"; data: string }
+  | { type: "resize"; cols: number; rows: number }
+  | { type: "status"; status: TerminalStatus };
+
+const cellSchema = z.strictObject({ text: z.string(), width: z.number(), fg: z.string(), bg: z.string(), bold: z.boolean(), italic: z.boolean(), underline: z.boolean(), strike: z.boolean() });
+export const terminalImageSchema = z.strictObject({ cols: z.number(), rows: z.number(), cursor: z.strictObject({ x: z.number(), y: z.number(), visible: z.boolean() }), cells: z.array(z.array(cellSchema)) });
+export type TerminalImage = z.infer<typeof terminalImageSchema>;

package/src/tool-result.ts

@@ -0,0 +1,45 @@
+import { z } from "zod";
+import { jsonSchema, type Json } from "./json.ts";
+import { contractReferenceSchema } from "./presentation.ts";
+import { modelInputPartsSchema, type ModelInputPart } from "./model-input.ts";
+
+export const toolResourceSchema = z.strictObject({ id: z.string(), kind: z.string(), title: z.string() });
+/** Identity selected for this request; history display must not substitute the current resource or current implementation. */
+export const toolInvocationSchema = z.strictObject({
+  implementation: contractReferenceSchema.optional(),
+  resource: toolResourceSchema.optional(),
+  startedAt: z.number().nonnegative().optional(),
+  finishedAt: z.number().nonnegative().optional(),
+});
+export type ToolInvocationInfo = z.infer<typeof toolInvocationSchema>;
+
+const error = z.strictObject({ code: z.string(), message: z.string() });
+export const toolCompletionSchema = z.discriminatedUnion("kind", [
+  z.strictObject({ kind: z.literal("succeeded"), data: jsonSchema }),
+  z.strictObject({ kind: z.literal("partial"), data: jsonSchema, message: z.string() }),
+  z.strictObject({ kind: z.literal("rejected"), data: jsonSchema, error }),
+  z.strictObject({ kind: z.literal("failed"), data: jsonSchema, error }),
+  z.strictObject({ kind: z.literal("cancelled"), data: jsonSchema, message: z.string() }),
+  z.strictObject({ kind: z.literal("unknown"), data: jsonSchema, message: z.string() }),
+]);
+export const toolRunningResultSchema = z.strictObject({ kind: z.literal("running"), data: jsonSchema });
+type WithData<T, D> = T extends unknown ? Omit<T, "data"> & { data: D | null } : never;
+export type ToolCompletion<D = Json> = WithData<z.infer<typeof toolCompletionSchema>, D>;
+/** Progress and terminal states share the data contract; null means no valid output yet. */
+export type ToolResult<D = Json> = { kind: "running"; data: D | null } | ToolCompletion<D>;
+/** Model projection and user input share text | file parts; only success and partial success may carry files. */
+const saved = { ...toolInvocationSchema.shape, model: modelInputPartsSchema };
+function extendSaved<I extends 0 | 1 | 2 | 3 | 4 | 5>(index: I) { return toolCompletionSchema.options[index].extend(saved); }
+export const toolOutcomeSchema = z.discriminatedUnion("kind",
+  toolCompletionSchema.options.map(option => option.extend(saved)) as unknown as [
+    ReturnType<typeof extendSaved<0>>, ReturnType<typeof extendSaved<1>>, ReturnType<typeof extendSaved<2>>,
+    ReturnType<typeof extendSaved<3>>, ReturnType<typeof extendSaved<4>>, ReturnType<typeof extendSaved<5>>,
+  ]).refine(outcome => outcome.kind === "succeeded" || outcome.kind === "partial" || outcome.model.every(part => part.kind === "text"),
+  "Only succeeded or partial tool results can carry files.");
+export type ToolOutcome = z.infer<typeof toolOutcomeSchema>;
+/** Content passed from a tool to the model: a string becomes one text part; file parts reference immutable content staged during execution or already owned by the object. */
+export type ToolModelOutput = string | ModelInputPart[];
+/** Projection used when a tool declares no toModel: strings are text, other decoded values are JSON text. */
+export function defaultToolModel(data: Json): string {
+  return typeof data === "string" ? data : JSON.stringify(data);
+}

package/src/tool-validation.ts

@@ -0,0 +1,14 @@
+import type { z } from "zod";
+
+/** Preserve field paths and specific validation reasons from union branches so the model can correct the raw JSON arguments. */
+export function validationMessage(error: z.ZodError, field: string): string {
+  const format = (issues: readonly z.core.$ZodIssue[]): string => issues.map(issue => {
+    const path = [field, ...issue.path.map(String)].filter(Boolean).join(".");
+    return issue.code === "invalid_union"
+      ? `${path}: must match one of these alternatives: ${issue.errors.map(branch => `(${format(branch)})`).join(" OR ")}`
+      : `${path}: ${issue.message}`;
+  }).join("; ");
+  return format(error.issues);
+}
+
+export const jsonArgumentHint = "target and args are JSON values matching their schemas; objects and null retain their JSON types.";

package/src/usage-state.ts

@@ -0,0 +1,20 @@
+import { z } from "zod";
+import { defineCall } from "./calls.ts";
+import { defineEvent } from "./events.ts";
+import { providerUsageIdSchema, usageItemsSchema, providerUsageErrorSchema } from "./provider-usage.ts";
+
+/** Shared provider usage state; response consumption remains explicit. */
+export const providerUsageStateSchema = z.strictObject({
+  providerId: z.string(), usage: providerUsageIdSchema.nullable(),
+  source: z.enum(["query", "headers"]).optional(), model: z.string().optional(),
+  state: z.enum(["disabled", "waiting", "loading", "ready", "error"]),
+  items: usageItemsSchema, updatedAt: z.number().nonnegative().nullable(), error: providerUsageErrorSchema.nullable(),
+});
+export type ProviderUsageState = z.infer<typeof providerUsageStateSchema>;
+export const ReadUsage = defineCall("core.usage.read", {
+  scope: "plugin", input: z.strictObject({ providerId: z.string(), refresh: z.boolean() }), output: providerUsageStateSchema,
+});
+export const UsageChanged = defineEvent("core.usage.changed", {
+  schema: z.strictObject({ providerId: z.string().nullable() }),
+  source: "host", semantics: { kind: "snapshot", key: ["providerId"] },
+});

package/src/web.ts

@@ -0,0 +1,75 @@
+import { z } from "zod";
+import { presentationSchema } from "./presentation.ts";
+import { uiTextSchema } from "./i18n.ts";
+
+export const webUrlSchema = z.string().url().refine(value => {
+  const url = new URL(value);
+  return ["http:", "https:"].includes(url.protocol) && !url.username && !url.password;
+}, "An HTTP or HTTPS URL without embedded credentials is required.");
+export const webHintSchema = z.object({ code: z.string(), message: z.string(), parameter: z.string().optional() });
+export const webContentPartSchema = z.object({
+  kind: z.enum(["snippet", "excerpt", "body", "summary"]), format: z.enum(["text", "markdown"]), text: z.string(),
+  truncated: z.boolean().optional().describe("Known content truncation. Omitted when completeness is unknown."),
+});
+/** Dates retain upstream precision and kind; use unknown for an unknown date kind. */
+export const webDateSchema = z.object({ kind: z.enum(["published", "modified", "fetched", "unknown"]), value: z.string() });
+export const webDocumentSchema = z.object({
+  url: webUrlSchema, title: z.string().optional(), author: z.string().optional(),
+  dates: z.array(webDateSchema).optional(), content: z.array(webContentPartSchema),
+  image: webUrlSchema.optional(), favicon: webUrlSchema.optional(),
+  links: z.array(z.object({ url: webUrlSchema, title: z.string().optional() })).optional(),
+  /** Scores are interpreted by the actual provider; consumers preserve result order. */
+  score: z.number().finite().optional(), details: z.array(presentationSchema).optional(),
+});
+export const webUsageSchema = z.object({
+  name: z.string(), amount: z.number().finite(), unit: z.string(), currency: z.string().optional(),
+});
+export const webResponseSchema = z.object({
+  documents: z.array(webDocumentSchema), hints: z.array(webHintSchema),
+  requestId: z.string().optional(), usage: z.array(webUsageSchema).optional(), details: z.array(presentationSchema).optional(),
+});
+const date = z.union([z.iso.date(), z.iso.datetime({ offset: true })]);
+export const webSearchRequestSchema = z.object({
+  query: z.string().trim().min(1).describe("Web search query."),
+  maxResults: z.number().int().positive().default(10).describe("Maximum number of search results."),
+  includeDomains: z.array(z.string().trim().min(1)).optional().describe("Domains to include."),
+  excludeDomains: z.array(z.string().trim().min(1)).optional().describe("Domains to exclude."),
+  publishedAfter: date.optional().describe("Publication date lower bound, as an ISO date or timestamp."),
+  publishedBefore: date.optional().describe("Publication date upper bound, as an ISO date or timestamp."),
+  language: z.string().trim().min(1).optional().describe("Preferred content language."),
+  region: z.string().regex(/^[A-Z]{2}$/u).optional().describe("Two-letter country code for localized results."),
+}).describe("Search terms and optional filters. Result hints describe conditions that were not applied.");
+export const webFetchRequestSchema = z.object({
+  url: webUrlSchema.describe("URL to retrieve."),
+  query: z.string().trim().min(1).optional().describe("Optional focus for additional excerpts delivered alongside the page body. Excerpt retrieval may incur additional provider charges."),
+  maxCharacters: z.number().int().positive().optional().describe("Maximum body characters per document, counted as Unicode code points across body parts. Excerpts and metadata are separate. Omitted uses provider defaults."),
+}).describe("URL, optional additional excerpt focus and body character limit.");
+
+/** Providers declare credential types; the UI renders corresponding inputs by type and does not accept arbitrary JSON. */
+export const webCredentialDefinitionSchema = z.object({
+  kind: z.enum(["api_key"]),
+  keyUrl: webUrlSchema.optional(),
+});
+/** At most one configuration per provider type; id equals the type slug. */
+export const webProviderStateSchema = z.strictObject({
+  id: z.string().trim().min(1),
+  enabled: z.boolean(),
+});
+export const webProviderTypeSchema = z.object({
+  id: z.string().min(1), label: uiTextSchema, owner: z.string(),
+  search: z.boolean(), fetch: z.boolean(), urlPatterns: z.array(z.string().min(1)),
+  credential: webCredentialDefinitionSchema.nullable(),
+});
+/** provider in results is the type slug of the provider that actually handled the request. */
+export const webSearchResultSchema = webResponseSchema.extend({ query: z.string(), provider: z.string() });
+export const webFetchResultSchema = webResponseSchema.extend({ requestedUrl: webUrlSchema, provider: z.string() });
+export type WebHint = z.infer<typeof webHintSchema>;
+export type WebDocument = z.infer<typeof webDocumentSchema>;
+export type WebResponse = z.infer<typeof webResponseSchema>;
+export type WebSearchRequest = z.infer<typeof webSearchRequestSchema>;
+export type WebFetchRequest = z.infer<typeof webFetchRequestSchema>;
+export type WebCredentialDefinition = z.infer<typeof webCredentialDefinitionSchema>;
+export type WebProviderState = z.infer<typeof webProviderStateSchema>;
+export type WebProviderType = z.infer<typeof webProviderTypeSchema>;
+export type WebSearchResult = z.infer<typeof webSearchResultSchema>;
+export type WebFetchResult = z.infer<typeof webFetchResultSchema>;

package/src/workspace.ts

@@ -0,0 +1,43 @@
+/** Shared workbench read contracts: consumable by both backend and frontend, independent of host storage and Node. */
+import type { Json } from "./json.ts";
+import type { ResourceContract } from "./module-contract.ts";
+import type { SessionView } from "./records.ts";
+import { z } from "zod";
+
+/** Resource rename input; identity and external location do not change with the name. */
+export const resourceTitleSchema = z.string().max(160).regex(/\S/u, "The title must contain non-whitespace text.");
+export interface ResourceRef { readonly sessionId: string; readonly id: string; readonly kind: string }
+/** Identity and title at committed creation; the title is a result summary and does not participate in resource identity validation. */
+export interface ResourceCreationResult extends ResourceRef { readonly title: string }
+export interface SessionSummary { readonly id: string; readonly title: string; readonly createdAt: string }
+/** Archived session summary; archivedAt is the archival time, and startup cleanup deletes the session after the cooling-off period. */
+export interface ArchivedSessionSummary extends SessionSummary { readonly archivedAt: string }
+/**
+ * Read-only session catalog shared within the same host runtime instance; each read returns current summaries.
+ * list contains only active sessions; archived lists sessions in the recycle bin. Session IDs absent from both have been deleted, allowing plugins to clean up their own per-session data.
+ */
+export interface SessionDirectory { list(): readonly SessionSummary[]; archived(): readonly ArchivedSessionSummary[] }
+/** Source: null means the application itself; plugin-originated sources always include plugin identity, and resource sources always belong to that plugin. Shared by records, events, and others. */
+export type Source = { readonly plugin: string; readonly resource: ResourceRef | null } | null;
+export interface ResourceSnapshot<S extends Json = Json> {
+  readonly ref: ResourceRef;
+  readonly title: string;
+  readonly data: S;
+}
+/** Read-only observation handle with a fixed timeline tip and session read upper bound, distinct from the full tree and workbench projections in host IPC. */
+export interface SessionSnapshot extends SessionView {
+  readonly position: { readonly nodeId: string | null };
+  readonly resources: {
+    all(): readonly ResourceSnapshot[];
+    /**
+     * Resources directly linked to this receiver on the snapshot's timeline path, with captured titles and public data.
+     * Reverse and transitive links are independent. Returns an empty list if the receiver's session, identity, or kind does not match a present resource.
+     * Observing links does not expand a model request's captured operation scope.
+     */
+    linkedTo(receiver: ResourceRef): readonly ResourceSnapshot[];
+    get<S extends Json>(contract: ResourceContract<S>, id: string):
+      | { status: "known"; resource: ResourceSnapshot<S> }
+      | { status: "unknown"; resource: ResourceSnapshot; reason: "invalid_data" }
+      | null;
+  };
+}