wave-agent-sdk 1.2.0 → 1.3.0

package/dist/services/artifactContent.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Shared artifact content layer.
+ *
+ * The single implementation of artifact content retrieval: slug extraction,
+ * metadata probe (`via=model_read`), ownership detection, Bearer-authenticated
+ * content fetch, HTML→markdown conversion and large-content persistence.
+ * Both the Artifact tool's `read` action and WebFetch's artifact URL
+ * interception call into it (spec: 读取实现单一化).
+ */
+import type { ToolContext, ToolResult } from "../tools/types.js";
+/** Artifact content beyond this size is persisted to a temp file (path + preview). */
+export declare const ARTIFACT_PREVIEW_BYTES: number;
+/** Used when the caller reads someone else's artifact without a `prompt`. */
+export declare const DEFAULT_READ_SUMMARY_PROMPT = "Summarize this page: its purpose, structure, and key content.";
+/** Frame metadata returned by `GET /api/frame/{slug}?via=model_read`. */
+export interface FrameMeta {
+    slug?: string;
+    version?: string;
+    title?: string;
+    favicon?: string;
+    perm?: {
+        mode: "owner" | "users" | "org";
+        role?: string;
+    };
+    url?: string;
+    contentUrl?: string;
+    /** Empty/missing = shared-live (readers see live updates); non-empty = pinned. */
+    shared?: string;
+}
+/** The publishing user's relationship to an artifact. */
+export type ArtifactOwnership = "owner" | "reader";
+export interface ArtifactContent {
+    slug: string;
+    version: string;
+    ownership: ArtifactOwnership;
+    /** Raw HTML as stored server-side (inline CSS/JS preserved). */
+    html: string;
+    bytes: number;
+}
+export type FrameMetaResult = {
+    kind: "ok";
+    meta: FrameMeta;
+} | {
+    kind: "error";
+    status: number;
+    error: string;
+};
+export type ArtifactContentResult = {
+    kind: "ok";
+    artifact: ArtifactContent;
+} | {
+    kind: "error";
+    status?: number;
+    error: string;
+};
+/** Extract the artifact slug from a `{host}/code/artifact/{slug}` URL. */
+export declare function extractArtifactSlug(url: string): string | null;
+/** Probe artifact metadata; `via=model_read` marks model access. */
+export declare function fetchFrameMeta(slug: string, opts?: {
+    abortSignal?: AbortSignal;
+}): Promise<FrameMetaResult>;
+/**
+ * Read an artifact's content. Owner reads come back as raw HTML (inline CSS/JS
+ * intact); ownership is decided from the server metadata so readers of someone
+ * else's page can be routed to the isolated-summary path.
+ */
+export declare function readArtifactContent(slug: string, opts?: {
+    url?: string;
+    abortSignal?: AbortSignal;
+}): Promise<ArtifactContentResult>;
+/** Convert artifact HTML to markdown (the summary path feeds text, not markup). */
+export declare function htmlToMarkdown(html: string): string;
+/** Whether content is too large to return inline. */
+export declare function isLargeArtifactContent(content: string): boolean;
+/**
+ * Persist content to a temp file and return the `<persisted-output>` message.
+ * Returns null when the content is small enough to inline, or on write failure.
+ */
+export declare function persistArtifactContent(content: string): string | null;
+/**
+ * Reader view: run someone else's artifact through the fast model and return
+ * only the answer, so the full page never reaches the main conversation.
+ */
+export declare function summarizeArtifactAsReader(url: string, prompt: string, html: string, context: ToolContext): Promise<ToolResult>;

package/dist/services/artifactContent.js

@@ -0,0 +1,204 @@
+/**
+ * Shared artifact content layer.
+ *
+ * The single implementation of artifact content retrieval: slug extraction,
+ * metadata probe (`via=model_read`), ownership detection, Bearer-authenticated
+ * content fetch, HTML→markdown conversion and large-content persistence.
+ * Both the Artifact tool's `read` action and WebFetch's artifact URL
+ * interception call into it (spec: 读取实现单一化).
+ */
+import TurndownService from "turndown";
+import { authService, createAuthAwareFetch } from "./authService.js";
+import { logger } from "../utils/globalLogger.js";
+import { buildPersistedOutputMessage, generatePreview, persistToolResult, } from "../utils/toolResultStorage.js";
+import { processContentWithAI } from "./contentSummarizer.js";
+/** Metadata/content request timeout. */
+const ARTIFACT_READ_TIMEOUT_MS = 60000;
+/** Artifact content beyond this size is persisted to a temp file (path + preview). */
+export const ARTIFACT_PREVIEW_BYTES = 2 * 1024;
+/** Inline fallback when persisting large content fails. */
+const MAX_INLINE_ARTIFACT_CHARS = 100000;
+/** Used when the caller reads someone else's artifact without a `prompt`. */
+export const DEFAULT_READ_SUMMARY_PROMPT = "Summarize this page: its purpose, structure, and key content.";
+/** Extract the artifact slug from a `{host}/code/artifact/{slug}` URL. */
+export function extractArtifactSlug(url) {
+    try {
+        const parsed = new URL(url);
+        const match = parsed.pathname.match(/^\/code\/artifact\/([^/]+)\/?$/);
+        return match ? decodeURIComponent(match[1]) : null;
+    }
+    catch {
+        return null;
+    }
+}
+function readSignal(abortSignal) {
+    return abortSignal
+        ? AbortSignal.any([
+            abortSignal,
+            AbortSignal.timeout(ARTIFACT_READ_TIMEOUT_MS),
+        ])
+        : AbortSignal.timeout(ARTIFACT_READ_TIMEOUT_MS);
+}
+/** Probe artifact metadata; `via=model_read` marks model access. */
+export async function fetchFrameMeta(slug, opts = {}) {
+    const serverUrl = authService.getServerUrl();
+    const authFetch = createAuthAwareFetch(globalThis.fetch);
+    try {
+        const res = await authFetch(`${serverUrl}/api/frame/${encodeURIComponent(slug)}?via=model_read`, { method: "GET", signal: readSignal(opts.abortSignal) });
+        if (!res.ok) {
+            return {
+                kind: "error",
+                status: res.status,
+                error: `Failed to fetch artifact metadata: ${res.status} ${res.statusText}`,
+            };
+        }
+        return { kind: "ok", meta: (await res.json()) };
+    }
+    catch (error) {
+        logger?.warn("Artifact metadata probe failed", {
+            slug,
+            error: String(error),
+        });
+        return {
+            kind: "error",
+            status: 0,
+            error: `Failed to fetch artifact metadata: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+}
+/**
+ * Read an artifact's content. Owner reads come back as raw HTML (inline CSS/JS
+ * intact); ownership is decided from the server metadata so readers of someone
+ * else's page can be routed to the isolated-summary path.
+ */
+export async function readArtifactContent(slug, opts = {}) {
+    const displayUrl = opts.url || slug;
+    const metaResult = await fetchFrameMeta(slug, {
+        abortSignal: opts.abortSignal,
+    });
+    if (metaResult.kind === "error") {
+        if (metaResult.status === 404) {
+            return {
+                kind: "error",
+                status: 404,
+                error: `Artifact not found: ${displayUrl} (it may have been deleted)`,
+            };
+        }
+        if (metaResult.status === 403) {
+            return {
+                kind: "error",
+                status: 403,
+                error: `You do not have permission to read this artifact: ${displayUrl}`,
+            };
+        }
+        return {
+            kind: "error",
+            status: metaResult.status,
+            error: metaResult.error,
+        };
+    }
+    const meta = metaResult.meta;
+    const version = typeof meta.version === "string" ? meta.version : "";
+    const contentUrl = typeof meta.contentUrl === "string" ? meta.contentUrl : "";
+    if (!contentUrl) {
+        return {
+            kind: "error",
+            error: "Artifact metadata did not include a contentUrl",
+        };
+    }
+    // Unknown ownership is treated as reader-owned: never hand out full text of a
+    // page we cannot prove the user owns.
+    const ownership = meta.perm?.mode === "owner" || meta.perm?.role === "owner"
+        ? "owner"
+        : "reader";
+    const serverUrl = authService.getServerUrl();
+    const authFetch = createAuthAwareFetch(globalThis.fetch);
+    let html;
+    try {
+        const res = await authFetch(new URL(contentUrl, serverUrl).toString(), {
+            method: "GET",
+            signal: readSignal(opts.abortSignal),
+        });
+        if (res.status === 403) {
+            return {
+                kind: "error",
+                status: 403,
+                error: `You do not have permission to read this artifact: ${displayUrl}`,
+            };
+        }
+        if (!res.ok) {
+            return {
+                kind: "error",
+                status: res.status,
+                error: `Failed to fetch artifact content: ${res.status} ${res.statusText}`,
+            };
+        }
+        html = await res.text();
+    }
+    catch (error) {
+        logger?.warn("Artifact content fetch failed", {
+            slug,
+            error: String(error),
+        });
+        return {
+            kind: "error",
+            error: `Failed to fetch artifact content: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+    return {
+        kind: "ok",
+        artifact: {
+            slug,
+            version,
+            ownership,
+            html,
+            bytes: new TextEncoder().encode(html).length,
+        },
+    };
+}
+/** Convert artifact HTML to markdown (the summary path feeds text, not markup). */
+export function htmlToMarkdown(html) {
+    return new TurndownService().turndown(html);
+}
+/** Whether content is too large to return inline. */
+export function isLargeArtifactContent(content) {
+    return new TextEncoder().encode(content).length > ARTIFACT_PREVIEW_BYTES;
+}
+/**
+ * Persist content to a temp file and return the `<persisted-output>` message.
+ * Returns null when the content is small enough to inline, or on write failure.
+ */
+export function persistArtifactContent(content) {
+    if (!isLargeArtifactContent(content))
+        return null;
+    const filePath = persistToolResult(content, "artifact");
+    if (!filePath)
+        return null;
+    return buildPersistedOutputMessage(content.length, filePath, generatePreview(content));
+}
+/**
+ * Reader view: run someone else's artifact through the fast model and return
+ * only the answer, so the full page never reaches the main conversation.
+ */
+export async function summarizeArtifactAsReader(url, prompt, html, context) {
+    const markdown = htmlToMarkdown(html);
+    const bytes = new TextEncoder().encode(markdown).length;
+    const persisted = persistArtifactContent(markdown);
+    let aiInput = markdown;
+    if (persisted) {
+        aiInput = persisted;
+    }
+    else if (bytes > ARTIFACT_PREVIEW_BYTES) {
+        aiInput =
+            markdown.substring(0, MAX_INLINE_ARTIFACT_CHARS) +
+                "\n\n... (content truncated, failed to persist full output)";
+    }
+    const result = await processContentWithAI(url, prompt || DEFAULT_READ_SUMMARY_PROMPT, aiInput, 200, "OK", context, bytes);
+    if (persisted) {
+        // Append the persisted-output message so the model can Read the full text.
+        result.content = result.content
+            ? result.content + "\n\n" + persisted
+            : persisted;
+    }
+    return result;
+}

package/dist/services/artifactSession.d.ts

@@ -7,6 +7,8 @@
  * - slug → latest known version: powers the stale-version guard
  *   (local knowledge older than the live version blocks a redeploy
  *   unless `force` is set) and lets WebFetch record versions it observed.
+ * - slug → read approval: reading someone else's artifact is confirmed once
+ *   per session; later reads of the same page are not re-confirmed.
  *
  * State is keyed by sessionId so parallel sessions never observe each other.
  */
@@ -23,5 +25,9 @@ export declare function getArtifactByFilePath(sessionId: string, filePath: strin
 export declare function getRecordedVersion(sessionId: string, slug: string): string | undefined;
 /** Record an observed version (from a publish, a 409 conflict, or a WebFetch read). */
 export declare function recordVersion(sessionId: string, slug: string, version: string): void;
+/** Remember that the user approved reading someone else's artifact this session. */
+export declare function markArtifactReadApproved(sessionId: string, slug: string): void;
+/** Whether the user already approved reading this artifact in this session. */
+export declare function isArtifactReadApproved(sessionId: string, slug: string): boolean;
 /** Clear all session-scoped artifact state (used when a session ends). */
 export declare function clearArtifactSession(sessionId: string): void;

package/dist/services/artifactSession.js

@@ -7,11 +7,14 @@
  * - slug → latest known version: powers the stale-version guard
  *   (local knowledge older than the live version blocks a redeploy
  *   unless `force` is set) and lets WebFetch record versions it observed.
+ * - slug → read approval: reading someone else's artifact is confirmed once
+ *   per session; later reads of the same page are not re-confirmed.
  *
  * State is keyed by sessionId so parallel sessions never observe each other.
  */
 const sessionArtifacts = new Map();
 const sessionSlugVersions = new Map();
+const sessionReadApprovals = new Map();
 function fileMapFor(sessionId) {
     let map = sessionArtifacts.get(sessionId);
     if (!map) {
@@ -45,8 +48,22 @@ export function getRecordedVersion(sessionId, slug) {
 export function recordVersion(sessionId, slug, version) {
     slugMapFor(sessionId).set(slug, version);
 }
+/** Remember that the user approved reading someone else's artifact this session. */
+export function markArtifactReadApproved(sessionId, slug) {
+    let set = sessionReadApprovals.get(sessionId);
+    if (!set) {
+        set = new Set();
+        sessionReadApprovals.set(sessionId, set);
+    }
+    set.add(slug);
+}
+/** Whether the user already approved reading this artifact in this session. */
+export function isArtifactReadApproved(sessionId, slug) {
+    return sessionReadApprovals.get(sessionId)?.has(slug) ?? false;
+}
 /** Clear all session-scoped artifact state (used when a session ends). */
 export function clearArtifactSession(sessionId) {
     sessionArtifacts.delete(sessionId);
     sessionSlugVersions.delete(sessionId);
+    sessionReadApprovals.delete(sessionId);
 }

package/dist/services/autoMemoryService.js

@@ -1,7 +1,7 @@
 import * as path from "node:path";
-import * as fs from "node:fs/promises";
 import { logger } from "../utils/globalLogger.js";
 import { isPathInside } from "../utils/pathSafety.js";
+import { formatMemoryManifest, scanMemoryFiles } from "../utils/memoryIndex.js";
 import { buildAutoMemoryExtractionPrompt } from "../prompts/autoMemoryExtraction.js";
 import { READ_ONLY_COMMANDS, splitBashCommand, hasWriteRedirections, hasCommandSubstitution, hasProcessSubstitution, hasSedInPlace, isDangerousFind, } from "../utils/bashParser.js";
 /**
@@ -140,18 +140,10 @@ export class AutoMemoryService {
         const memoryDir = this.memoryService.getAutoMemoryDirectory(workdir);
         // Ensure memory directory exists before starting
         await this.memoryService.ensureAutoMemoryDirectory(workdir);
-        // Prepare manifest of existing memory files
-        let existingMemoriesManifest = "";
-        try {
-            const files = await fs.readdir(memoryDir);
-            existingMemoriesManifest = files
-                .filter((f) => f.endsWith(".md"))
-                .map((f) => `- ${f}`)
-                .join("\n");
-        }
-        catch {
-            // Ignore if directory doesn't exist yet
-        }
+        // Prepare manifest of existing memory files: type tag, filename, timestamp
+        // and description, so the fork can tell whether a memory already exists
+        // without spending a turn on `ls`.
+        const existingMemoriesManifest = formatMemoryManifest(await scanMemoryFiles(memoryDir));
         const prompt = buildAutoMemoryExtractionPrompt(newMessageCount, existingMemoriesManifest);
         await this.aiManager.runAutoMemoryFork(messages, `${prompt}\n\nThe memory directory for this project is: ${memoryDir}`, {
             maxTurns: 5, // Limit turns to prevent verification rabbit-holes

package/dist/services/configurationService.d.ts

@@ -15,6 +15,15 @@ import { ClientOptions } from "openai";
  * session cleanup runs before config is loaded).
  */
 export declare function validateConfigurationObject(config: WaveConfiguration): ValidationResult;
+/**
+ * The settings.json-derived configuration a turn reads from, captured when the
+ * turn started (see {@link ConfigurationService.setTurnSnapshotSource}). Held
+ * while a turn runs so a live reload can't shift values under it.
+ */
+export interface TurnConfigurationSnapshot {
+    configuration: WaveConfiguration | null;
+    env: Record<string, string>;
+}
 /**
  * Default ConfigurationService implementation
  *
@@ -26,10 +35,19 @@ export declare class ConfigurationService {
     private options;
     private _configuredEnvKeys;
     private envSnapshot;
+    private turnSnapshotSource?;
+    /**
+     * Register the turn-snapshot source (see {@link TurnConfigurationSnapshot}).
+     */
+    setTurnSnapshotSource(source: () => TurnConfigurationSnapshot | null): void;
     /**
      * Set agent options for configuration resolution
      */
     setOptions(options: AgentOptions): void;
+    /** Configuration the current turn reads from (live configuration outside a turn). */
+    private get liveConfiguration();
+    /** Environment snapshot the current turn reads from. */
+    private get liveEnvSnapshot();
     /**
      * Returns a copy of the per-session environment snapshot (settings.json `env`).
      * Priority over OS env; does NOT include OS env. For subprocess spawning use
@@ -101,17 +119,30 @@ export declare class ConfigurationService {
     resolveMaxInputTokens(constructorLimit?: number, model?: string): number;
     /**
      * Resolves preferred language with fallbacks
-     * Resolution priority: override > options > settings.json > undefined
+     * Resolution priority: override > options > settings.json > default (`zh-CN`)
+     *
+     * 末尾的默认值保证「未设置」时也有明确生效值，且与设置页下拉的默认项一致
+     * （spec agent-config 边界说明「语言默认值」）。调用方不得再假定
+     * 「undefined = 不注入语言指令」。
+     *
      * @param constructorLanguage - Language override (optional)
-     * @returns Resolved language or undefined
+     * @returns Resolved language (never empty)
      */
-    resolveLanguage(constructorLanguage?: string): string | undefined;
+    resolveLanguage(constructorLanguage?: string): string;
     /**
      * Resolves auto-memory enabled state with fallbacks
-     * Resolution priority: session options (host settings-page value) > settings.json > WAVE_DISABLE_AUTO_MEMORY > default (true)
+     * Resolution priority: session options (session-level override) > settings.json > WAVE_DISABLE_AUTO_MEMORY > default (true)
      * @returns Resolved auto-memory enabled state
      */
     resolveAutoMemoryEnabled(): boolean;
+    /**
+     * Same resolution chain but read from the live merged configuration, ignoring
+     * the turn snapshot. The permission safe zone is a live mechanism (like
+     * permission rules, applied by LiveConfigManager on reload), so its sync must
+     * not be pinned to the turn-start value.
+     */
+    resolveAutoMemoryEnabledNow(): boolean;
+    private resolveAutoMemoryEnabledFrom;
     /**
      * Resolves worktree base ref with fallbacks
      * Resolution priority: settings.json > default ("fresh")
@@ -120,7 +151,7 @@ export declare class ConfigurationService {
     resolveWorktreeBaseRef(): "fresh" | "head";
     /**
      * Resolves auto-memory extraction frequency with fallbacks
-     * Resolution priority: session options (host settings-page value) > settings.json > WAVE_AUTO_MEMORY_FREQUENCY > default (1)
+     * Resolution priority: session options (程序化会话级覆盖) > settings.json > WAVE_AUTO_MEMORY_FREQUENCY > default (1)
      * @returns Resolved auto-memory extraction frequency (turns)
      */
     resolveAutoMemoryFrequency(): number;
@@ -132,9 +163,13 @@ export declare class ConfigurationService {
      */
     resolveMaxOutputTokens(constructorLimit?: number): number;
     /**
-     * Set the active model in the session
+     * Set the active model in the session.
+     *
+     * Persisting to `~/.wave/settings.json` is best-effort: the in-memory model
+     * applies immediately, and a failed write (e.g. a locked file / rename EPERM
+     * on Windows) is logged instead of escaping as an unhandled rejection.
      */
-    setModel(model: string): void;
+    setModel(model: string): Promise<void>;
     private persistModelToSettings;
     /**
      * Get all configured models from settings.json and environment
@@ -184,9 +219,16 @@ export declare class ConfigurationService {
      */
     deleteHook(workdir: string, scope: Scope, hookName: string): Promise<void>;
     /**
-     * Get merged marketplaces from all scopes
+     * Get merged marketplaces from all scopes, with admin-managed (remote) entries
+     * taking precedence per key (spec enterprise server-managed-config「托管配置
+     * 下发插件市场与启用列表」场景 5).
      */
     getMergedMarketplaces(workdir: string): Record<string, MarketplaceConfig>;
+    /**
+     * Marketplaces declared by the remote (managed) settings. `null` means the
+     * managed layer declares none, leaving the local configuration chain in charge.
+     */
+    getManagedMarketplaces(): Record<string, MarketplaceConfig> | null;
     /**
      * Get marketplaces at a specific scope
      */
@@ -204,9 +246,18 @@ export declare class ConfigurationService {
      */
     removeEnabledPlugin(workdir: string, scope: Scope, pluginId: string): Promise<void>;
     /**
-     * Get merged enabled plugins from all scopes
+     * Get merged enabled plugins from all scopes, with admin-managed (remote)
+     * entries taking precedence per key (spec enterprise server-managed-config
+     * 「托管配置下发插件市场与启用列表」场景 5). A managed `false` therefore
+     * force-disables a plugin no matter what the local files say.
      */
     getMergedEnabledPlugins(workdir: string): Record<string, boolean>;
+    /**
+     * Enabled-plugin entries declared by the remote (managed) settings. `null`
+     * means the managed layer declares none. Doubles as the authoritative
+     * "is this plugin managed by the organization" lookup (spec plugin A-024).
+     */
+    getManagedEnabledPlugins(): Record<string, boolean> | null;
     /**
      * Load Wave configuration from a JSON file
      * Supports both hooks and environment variables with proper validation