opencode-metrics-plugin 0.2.0 → 0.3.0

package/dist/metrics/engine/state.js

@@ -78,6 +78,8 @@ export function createSessionMetrics(sessionId) {
         _roundFirstBuildTracked: false,
         _roundIdleProcessed: false,
         _idleFlushed: false,
+        _checkpointDirty: false,
+        _flushBaseline: null,
         planningCalls: [],
         systemPrompts: new Map(),
     };

package/dist/metrics/index.d.ts

@@ -6,4 +6,7 @@ export { createEventLogger } from './eventlog/event-logger.js';
 export type { EventLogger, EventLoggerOptions } from './eventlog/event-logger.js';
 export { createMetricsRuntime } from './runtime.js';
 export type { MetricsRuntime, MetricsRuntimeOptions } from './runtime.js';
+export { createUploadManager } from './upload/uploadManager.js';
+export type { UploadManager, UploadManagerOptions } from './upload/uploadManager.js';
+export type { UploadConfig, ScenarioConfig, ArtifactRule, UploadPackage } from './upload/types.js';
 export * from './types.js';

package/dist/metrics/index.js

@@ -3,4 +3,5 @@ export { createMetricsEngine } from './engine/engine.js';
 export { configureDirs, defaultDirs, getDirs, resolveDirs, getMetricsDir, getEventsDir, getLogFile } from './dirs.js';
 export { createEventLogger } from './eventlog/event-logger.js';
 export { createMetricsRuntime } from './runtime.js';
+export { createUploadManager } from './upload/uploadManager.js';
 export * from './types.js';

package/dist/metrics/runtime.d.ts

@@ -1,10 +1,13 @@
 import type { MetricsEngineOptions } from './engine/engine.js';
 import type { MetricsDirs } from './dirs.js';
+import type { UploadConfig } from './upload/types.js';
 export interface MetricsRuntimeOptions extends Omit<MetricsEngineOptions, 'enabled'> {
     dirs?: Partial<MetricsDirs>;
     enabled?: boolean;
     /** 事件写盘（events/<sessionId>.log；steps 全文的数据源） */
     eventLogging?: boolean;
+    /** 上传子系统配置（DESIGN.md §13.8）；enabled:true 才会创建管理器 */
+    upload?: UploadConfig;
 }
 /**
  * 组装一整套"通用统计插件"的运行时：事件记录 + 指标引擎。
@@ -14,6 +17,7 @@ export declare function createMetricsRuntime(opts?: MetricsRuntimeOptions): {
     dirs: MetricsDirs;
     eventLogger: import("./eventlog/event-logger.js").EventLogger | null;
     engine: import("./types.js").MetricsEngine;
+    uploadManager: import("./upload/uploadManager.js").UploadManager | null;
     /** opencode event hook：`async ({ event }) => { runtime.event({ event }) }` */
     event(input: {
         event: {

package/dist/metrics/runtime.js

@@ -1,6 +1,7 @@
 import { createMetricsEngine } from './engine/engine.js';
 import { createEventLogger } from './eventlog/event-logger.js';
 import { resolveDirs } from './dirs.js';
+import { createUploadManager } from './upload/uploadManager.js';
 /**
  * 组装一整套"通用统计插件"的运行时：事件记录 + 指标引擎。
  * 目录为实例级（不产生全局副作用）：defaultDirs → 进程级默认（configureDirs）→ opts.dirs 三层合并。
@@ -11,18 +12,27 @@ export function createMetricsRuntime(opts = {}) {
         enabled: opts.enabled,
         dirs,
         onFlush: opts.onFlush,
+        checkpointFlushIntervalMs: opts.checkpointFlushIntervalMs,
     });
     const eventLogger = (opts.eventLogging ?? true)
         ? createEventLogger(true, false, { eventsDir: dirs.eventsDir })
         : null;
+    // 上传管理器旁路挂在 runtime.event 上（在 engine.ingest 之后，保证触发时快照已落盘）
+    const uploadManager = createUploadManager({
+        config: opts.upload,
+        dirs,
+        onBeforeArchive: () => eventLogger?.flush(),
+    });
     return {
         dirs,
         eventLogger,
         engine,
+        uploadManager,
         /** opencode event hook：`async ({ event }) => { runtime.event({ event }) }` */
         event(input) {
             eventLogger?.log(input.event);
             engine.ingest(input.event);
+            uploadManager?.observe(input.event);
         },
     };
 }

package/dist/metrics/snapshot/flush.d.ts

@@ -1,6 +1,23 @@
 import type { MetricsDirs } from "../dirs.js";
 import type { SessionMetricsState } from "../engine/state.js";
 import type { MetricsOutput } from "../types.js";
+/**
+ * 把会话当前状态落盘为快照文件（读旧文件 → 合并 → 原子覆盖写）。
+ * 可重复调用，不会造成数据重复累计。
+ *
+ * @param sessionId 会话 id，快照文件名为 `<sessionId>.json`
+ * @param state     会话状态，写盘成功后原地刷新差量基线
+ * @param now       本次快照的结束时间（ms）
+ * @param dirs      输出目录；缺省用进程级默认目录
+ * @returns         本次由内存态构建的快照（未与旧文件合并的那份）
+ */
 declare function flushMetrics(sessionId: string, state: SessionMetricsState, now: number, dirs?: Partial<MetricsDirs>): MetricsOutput;
+/**
+ * 处理一轮会话结束：保存本轮 round 快照并落盘。
+ *
+ * @param state     会话状态（就地结算与重置；重复 idle 直接跳过）
+ * @param sessionId 会话 id
+ * @param dirs      输出目录；缺省用进程级默认目录
+ */
 declare function handleSessionIdle(state: SessionMetricsState, sessionId: string, dirs?: Partial<MetricsDirs>): MetricsOutput | undefined;
 export { flushMetrics, handleSessionIdle };

package/dist/metrics/snapshot/flush.js

@@ -14,12 +14,25 @@ function filterByKeys(source, keys) {
     }
     return result;
 }
+/**
+ * 把会话当前状态落盘为快照文件（读旧文件 → 合并 → 原子覆盖写）。
+ * 可重复调用，不会造成数据重复累计。
+ *
+ * @param sessionId 会话 id，快照文件名为 `<sessionId>.json`
+ * @param state     会话状态，写盘成功后原地刷新差量基线
+ * @param now       本次快照的结束时间（ms）
+ * @param dirs      输出目录；缺省用进程级默认目录
+ * @returns         本次由内存态构建的快照（未与旧文件合并的那份）
+ */
 function flushMetrics(sessionId, state, now, dirs) {
     // Finalize agent usage for current agent
     if (state.agent.current) {
         const elapsed = now - state.agent.lastSwitchTime;
-        const prev = state.agent.usage.get(state.agent.current) ?? 0;
-        state.agent.usage.set(state.agent.current, prev + elapsed);
+        const agent = state.agent.current;
+        const prev = state.agent.usage.get(agent) ?? 0;
+        state.agent.usage.set(agent, prev + elapsed);
+        // 重置计时起点，避免下次 flush 重复累计这段时长
+        state.agent.lastSwitchTime = now;
     }
     const endTime = now;
     const duration = endTime - state.startTime;
@@ -318,20 +331,36 @@ function flushMetrics(sessionId, state, now, dirs) {
         try {
             const existingRaw = fs.readFileSync(filePath, "utf-8");
             const existingOutput = JSON.parse(existingRaw);
-            merged = { ...mergeMetricsOutput(existingOutput, output), source: "live" };
+            // 同进程多次 flush（checkpoint）按差量并入，跨进程 baseline 为空（全量并入）
+            merged = { ...mergeMetricsOutput(existingOutput, output, state._flushBaseline), source: "live" };
         }
         catch {
-            // File doesn't exist or is corrupted 鈥?use fresh output
+            // File doesn't exist or is corrupted — use fresh output
         }
         const tmpPath = filePath + ".tmp";
         fs.writeFileSync(tmpPath, JSON.stringify(merged, null, 2));
         fs.renameSync(tmpPath, filePath);
+        // 写盘成功后刷新差量基线
+        state._flushBaseline = {
+            errorCodeCounts: Object.fromEntries(output.codeStats.errorCodes.map(e => [e.code, e.count])),
+            warningCounts: { ...output.codeStats.warnings.byType },
+            warningEntriesTotal: output.codeStats.warnings.entries.length,
+            moduleTimings: Object.fromEntries(output.codeStats.moduleTimings.map(m => [m.module, { totalDuration: m.totalDurationMs, taskCount: m.taskCount }])),
+            fixCycleCount: output.codeStats.fixCycles.cycles.length,
+        };
     }
     catch (err) {
         log.info("Failed to flush metrics", { sessionId, error: String(err) });
     }
     return output;
 }
+/**
+ * 处理一轮会话结束：保存本轮 round 快照并落盘。
+ *
+ * @param state     会话状态（就地结算与重置；重复 idle 直接跳过）
+ * @param sessionId 会话 id
+ * @param dirs      输出目录；缺省用进程级默认目录
+ */
 function handleSessionIdle(state, sessionId, dirs) {
     const now = Date.now();
     // Build round snapshot
@@ -384,6 +413,7 @@ function handleSessionIdle(state, sessionId, dirs) {
     // Flush metrics to disk
     state.endTime = now;
     state._idleFlushed = true;
+    state._checkpointDirty = false;
     return flushMetrics(sessionId, state, now, dirs);
 }
 export { flushMetrics, handleSessionIdle };

package/dist/metrics/snapshot/merge.d.ts

@@ -1,9 +1,17 @@
 import type { MetricsOutput } from "../types.js";
-import type { SessionMetricsState } from "../engine/state.js";
+import type { FlushBaseline, SessionMetricsState } from "../engine/state.js";
 declare function mergeChildMetrics(parent: SessionMetricsState, child: SessionMetricsState, meta: {
     childId: string;
     agentName: string;
     title: string;
 }): void;
-export declare function mergeMetricsOutput(existing: MetricsOutput | null, fresh: MetricsOutput): MetricsOutput;
+/**
+ * 合并磁盘旧快照与内存新快照：覆盖类字段取新值，累加类字段只补差量。
+ *
+ * @param existing 磁盘上的旧快照；null 时直接返回 fresh
+ * @param fresh    由当前内存态构建的新快照
+ * @param baseline 上次 flush 时累加字段的累计值，用于计算本次差量；null 时累加字段全量并入
+ * @returns        合并后的快照，可安全反复写盘
+ */
+export declare function mergeMetricsOutput(existing: MetricsOutput | null, fresh: MetricsOutput, baseline?: FlushBaseline | null): MetricsOutput;
 export { mergeChildMetrics };

package/dist/metrics/snapshot/merge.js

@@ -123,7 +123,15 @@ function mergeChildMetrics(parent, child, meta) {
     // Merge planning data
     parent.planningCalls.push(...child.planningCalls);
 }
-export function mergeMetricsOutput(existing, fresh) {
+/**
+ * 合并磁盘旧快照与内存新快照：覆盖类字段取新值，累加类字段只补差量。
+ *
+ * @param existing 磁盘上的旧快照；null 时直接返回 fresh
+ * @param fresh    由当前内存态构建的新快照
+ * @param baseline 上次 flush 时累加字段的累计值，用于计算本次差量；null 时累加字段全量并入
+ * @returns        合并后的快照，可安全反复写盘
+ */
+export function mergeMetricsOutput(existing, fresh, baseline) {
     if (!existing)
         return fresh;
     // startTime: min of both
@@ -191,53 +199,78 @@ export function mergeMetricsOutput(existing, fresh) {
     for (const s of fresh.skillSearches)
         searchMap.set(`${s.query}:${s.skillPath}`, s);
     const skillSearches = [...searchMap.values()];
-    // codeStats.errorCodes: merge by code, accumulate count, keep existing type/message
+    // codeStats.errorCodes: merge by code with per-code increment（差量 = fresh - baseline）
     const errorCodeMap = new Map();
     for (const e of existing.codeStats.errorCodes)
         errorCodeMap.set(e.code, { ...e });
     for (const e of fresh.codeStats.errorCodes) {
+        const increment = Math.max(0, e.count - (baseline?.errorCodeCounts[e.code] ?? 0));
+        if (increment === 0)
+            continue;
         const prev = errorCodeMap.get(e.code);
         if (prev) {
-            prev.count += e.count;
+            prev.count += increment;
             // keep existing type/message
         }
         else {
-            errorCodeMap.set(e.code, { ...e });
+            errorCodeMap.set(e.code, { ...e, count: increment });
         }
     }
     const errorCodes = [...errorCodeMap.values()];
-    // codeStats.warnings: merge by type, accumulate count, append entries
+    // codeStats.warnings: merge by type with increment; entries 只并入新增尾部（fresh 侧数组只追加）
     const warnByType = { ...existing.codeStats.warnings.byType };
     const warnEntries = [...existing.codeStats.warnings.entries];
     let warnTotal = existing.codeStats.warnings.total;
     for (const [type, count] of Object.entries(fresh.codeStats.warnings.byType)) {
-        warnByType[type] = (warnByType[type] || 0) + count;
-        warnTotal += count;
+        const increment = Math.max(0, count - (baseline?.warningCounts[type] ?? 0));
+        if (increment === 0)
+            continue;
+        warnByType[type] = (warnByType[type] || 0) + increment;
+        warnTotal += increment;
+    }
+    const warnEntriesBaseline = baseline?.warningEntriesTotal ?? 0;
+    if (fresh.codeStats.warnings.entries.length > warnEntriesBaseline) {
+        warnEntries.push(...fresh.codeStats.warnings.entries.slice(warnEntriesBaseline));
     }
-    warnEntries.push(...fresh.codeStats.warnings.entries);
     const warnings = { total: warnTotal, byType: warnByType, entries: warnEntries };
-    // codeStats.moduleTimings: merge by module, accumulate totalDuration/taskCount, max slowestTask
+    // codeStats.moduleTimings: merge by module with duration/taskCount increment, max slowestTask
     const moduleMap = new Map();
     for (const m of existing.codeStats.moduleTimings)
         moduleMap.set(m.module, { ...m, slowestTask: { ...m.slowestTask } });
     for (const m of fresh.codeStats.moduleTimings) {
+        const base = baseline?.moduleTimings[m.module];
+        const durationIncrement = Math.max(0, m.totalDurationMs - (base?.totalDuration ?? 0));
+        const taskIncrement = Math.max(0, m.taskCount - (base?.taskCount ?? 0));
+        if (durationIncrement === 0 && taskIncrement === 0)
+            continue;
         const prev = moduleMap.get(m.module);
         if (prev) {
-            prev.totalDurationMs += m.totalDurationMs;
-            prev.taskCount += m.taskCount;
+            prev.totalDurationMs += durationIncrement;
+            prev.taskCount += taskIncrement;
             if (m.slowestTask.duration > prev.slowestTask.duration) {
                 prev.slowestTask = { ...m.slowestTask };
             }
         }
         else {
-            moduleMap.set(m.module, { ...m, slowestTask: { ...m.slowestTask } });
+            moduleMap.set(m.module, {
+                module: m.module,
+                totalDurationMs: durationIncrement,
+                taskCount: taskIncrement,
+                slowestTask: { ...m.slowestTask },
+            });
         }
     }
     const moduleTimings = [...moduleMap.values()];
-    // codeStats.fixCycles: append (skip dedup)
+    // codeStats.fixCycles: existing 全保留 + fresh 增量尾部（fresh 侧 cycles 只追加）
+    const fixCycleBaseline = baseline?.fixCycleCount ?? 0;
     const fixCycles = {
         ...fresh.codeStats.fixCycles,
-        cycles: [...existing.codeStats.fixCycles.cycles, ...fresh.codeStats.fixCycles.cycles],
+        cycles: [
+            ...existing.codeStats.fixCycles.cycles,
+            ...(fresh.codeStats.fixCycles.cycles.length > fixCycleBaseline
+                ? fresh.codeStats.fixCycles.cycles.slice(fixCycleBaseline)
+                : []),
+        ],
     };
     // codeStats.firstBuildPerRound: fresh accumulates all rounds, use fresh
     const firstBuildPerRound = fresh.codeStats.firstBuildPerRound;

package/dist/metrics/snapshot/steps.d.ts

@@ -8,6 +8,13 @@ declare function buildSteps(maps: {
     reasoningMap: Map<string, string>;
     toolOutputMap: Map<string, string>;
 }): StepData[];
+/**
+ * 从会话事件日志解析全文内容（text/reasoning/工具输出），增量读取只解析新增字节。
+ *
+ * @param sessionId 会话 id，日志文件名为 `<sessionId>.log`
+ * @param opts      eventsDir 指定日志目录；filterMsgIds 只收集这些消息
+ * @returns         textMap/reasoningMap（按 messageID）与 toolOutputMap（按 callID）；日志不存在时为空表
+ */
 declare function extractStepContent(sessionId: string, opts?: {
     eventsDir?: string;
     filterMsgIds?: Set<string>;
@@ -16,4 +23,11 @@ declare function extractStepContent(sessionId: string, opts?: {
     reasoningMap: Map<string, string>;
     toolOutputMap: Map<string, string>;
 };
-export { buildSteps, extractStepContent };
+/**
+ * 清除事件日志的增量解析缓存。
+ *
+ * @param sessionId 只清该会话的缓存；缺省清空全部
+ * @param eventsDir 日志目录，须与 extractStepContent 使用的路径一致
+ */
+declare function clearStepContentCache(sessionId?: string, eventsDir?: string): void;
+export { buildSteps, extractStepContent, clearStepContentCache };

package/dist/metrics/snapshot/steps.js

@@ -30,61 +30,125 @@ function buildSteps(maps, contentMaps) {
         };
     });
 }
-function extractStepContent(sessionId, opts) {
-    const textMap = new Map();
-    const reasoningMap = new Map();
-    const toolOutputMap = new Map();
-    const filterMsgIds = opts?.filterMsgIds;
-    try {
-        const filePath = path.join(opts?.eventsDir ?? getEventsDir(), `${sessionId}.log`);
-        const content = fs.readFileSync(filePath, "utf-8");
-        // Split by [timestamp] prefix (zero-width lookahead)
-        const blocks = content.split(/^(?=\[\d{4}-\d{2}-\d{2} )/m);
-        for (const block of blocks) {
-            const dataIdx = block.indexOf("  DATA: ");
-            if (dataIdx < 0)
-                continue;
-            const jsonStr = block.slice(dataIdx + 8);
-            if (!jsonStr.trim())
+const stepContentCaches = new Map();
+/**
+ * 解析事件块，把 text/reasoning 累积到对应消息、工具输出累积到对应调用。
+ *
+ * @param blocks       已切分的事件块字符串数组
+ * @param cache        累积结果的映射表（text/reasoning/工具输出）
+ * @param filterMsgIds 只收集这些消息 id；缺省收集全部
+ */
+function parseEventBlocks(blocks, cache, filterMsgIds) {
+    for (const block of blocks) {
+        const dataIdx = block.indexOf("  DATA: ");
+        if (dataIdx < 0)
+            continue;
+        const jsonStr = block.slice(dataIdx + 8);
+        if (!jsonStr.trim())
+            continue;
+        try {
+            const event = JSON.parse(jsonStr);
+            const props = event;
+            const part = props.part;
+            if (!part)
                 continue;
-            try {
-                const event = JSON.parse(jsonStr);
-                const props = event;
-                const part = props.part;
-                if (!part)
+            const partType = part.type;
+            const msgId = part.messageID;
+            if (partType === "text" && msgId) {
+                if (filterMsgIds && !filterMsgIds.has(msgId))
                     continue;
-                const partType = part.type;
-                const msgId = part.messageID;
-                if (partType === "text" && msgId) {
-                    if (filterMsgIds && !filterMsgIds.has(msgId))
-                        continue;
-                    const text = part.text || "";
-                    textMap.set(msgId, (textMap.get(msgId) || "") + text);
-                }
-                if (partType === "reasoning" && msgId) {
-                    if (filterMsgIds && !filterMsgIds.has(msgId))
-                        continue;
-                    const text = part.text || "";
-                    reasoningMap.set(msgId, (reasoningMap.get(msgId) || "") + text);
-                }
-                if (partType === "tool") {
-                    const callID = part.callID;
-                    const toolState = part.state;
-                    const status = toolState?.status;
-                    if (callID && (status === "completed" || status === "error")) {
-                        const output = toolState?.output || toolState?.raw || "";
-                        toolOutputMap.set(callID, output);
-                    }
+                const text = part.text || "";
+                cache.textMap.set(msgId, (cache.textMap.get(msgId) || "") + text);
+            }
+            if (partType === "reasoning" && msgId) {
+                if (filterMsgIds && !filterMsgIds.has(msgId))
+                    continue;
+                const text = part.text || "";
+                cache.reasoningMap.set(msgId, (cache.reasoningMap.get(msgId) || "") + text);
+            }
+            if (partType === "tool") {
+                const callID = part.callID;
+                const toolState = part.state;
+                const status = toolState?.status;
+                if (callID && (status === "completed" || status === "error")) {
+                    const output = toolState?.output || toolState?.raw || "";
+                    cache.toolOutputMap.set(callID, output);
                 }
             }
-            catch {
-                // Skip unparseable blocks
+        }
+        catch {
+            // Skip unparseable blocks
+        }
+    }
+}
+/**
+ * 从会话事件日志解析全文内容（text/reasoning/工具输出），增量读取只解析新增字节。
+ *
+ * @param sessionId 会话 id，日志文件名为 `<sessionId>.log`
+ * @param opts      eventsDir 指定日志目录；filterMsgIds 只收集这些消息
+ * @returns         textMap/reasoningMap（按 messageID）与 toolOutputMap（按 callID）；日志不存在时为空表
+ */
+function extractStepContent(sessionId, opts) {
+    const filePath = path.join(opts?.eventsDir ?? getEventsDir(), `${sessionId}.log`);
+    let cache = stepContentCaches.get(filePath);
+    if (!cache) {
+        cache = {
+            offset: 0,
+            remainder: "",
+            textMap: new Map(),
+            reasoningMap: new Map(),
+            toolOutputMap: new Map(),
+        };
+        stepContentCaches.set(filePath, cache);
+    }
+    try {
+        const stat = fs.statSync(filePath);
+        if (stat.size < cache.offset) {
+            // 轮转/截断：重置缓存全量重解析
+            cache.offset = 0;
+            cache.remainder = "";
+            cache.textMap.clear();
+            cache.reasoningMap.clear();
+            cache.toolOutputMap.clear();
+        }
+        if (stat.size > cache.offset) {
+            const length = stat.size - cache.offset;
+            const buffer = Buffer.alloc(length);
+            const fd = fs.openSync(filePath, "r");
+            try {
+                fs.readSync(fd, buffer, 0, length, cache.offset);
+            }
+            finally {
+                fs.closeSync(fd);
+            }
+            const content = cache.remainder + buffer.toString("utf-8");
+            const blocks = content.split(/^(?=\[\d{4}-\d{2}-\d{2} )/m);
+            // 末块无结尾换行 = 写入未完成，留到下次（写入器每个完整块必以 \n 结尾）
+            let holdback = "";
+            if (!content.endsWith("\n")) {
+                holdback = blocks.length > 0 ? blocks.pop() : "";
             }
+            parseEventBlocks(blocks, cache, opts?.filterMsgIds);
+            cache.remainder = holdback;
+            cache.offset = stat.size;
         }
     }
     catch {
-        // File doesn't exist or read error 鈥?return empty maps
+        // File doesn't exist or read error — return whatever cached (usually empty maps)
+    }
+    return { textMap: cache.textMap, reasoningMap: cache.reasoningMap, toolOutputMap: cache.toolOutputMap };
+}
+/**
+ * 清除事件日志的增量解析缓存。
+ *
+ * @param sessionId 只清该会话的缓存；缺省清空全部
+ * @param eventsDir 日志目录，须与 extractStepContent 使用的路径一致
+ */
+function clearStepContentCache(sessionId, eventsDir) {
+    if (sessionId === undefined) {
+        stepContentCaches.clear();
+        return;
     }
-    return { textMap, reasoningMap, toolOutputMap };
+    stepContentCaches.delete(path.join(eventsDir ?? getEventsDir(), `${sessionId}.log`));
 }
-export { buildSteps, extractStepContent };
+export { buildSteps, extractStepContent, clearStepContentCache };

package/dist/metrics/upload/agcUploader.d.ts

@@ -0,0 +1,65 @@
+import { type UploadPackage } from "./types.js";
+/** 上传结果：失败时给出原因与是否可重试（4xx 不可重试，5xx/429/网络错误可重试） */
+export type UploadOutcome = {
+    ok: true;
+} | {
+    ok: false;
+    retryable: boolean;
+    reason: string;
+};
+/** AGC 凭证与域名（agc-apiclient.json 内容，域名已按 region 解析） */
+export interface AgcCredentials {
+    client_id: string;
+    client_secret: string;
+    project_id: string;
+    region: string;
+    bucket_name: string;
+    api_domain: string;
+    storage_domain: string;
+    /** token 缓存目录；默认 ~/.agc_cache（与 upload_agc.py 共用缓存），测试可覆盖 */
+    tokenCacheDir?: string;
+}
+/** AGC 凭证默认文件：包内 assets/agc-apiclient.json（opencode.json 未配置 agcConfigPath 时使用） */
+export declare function defaultAgcConfigPath(): string;
+export type LoadCredentialsResult = {
+    ok: true;
+    credentials: AgcCredentials;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * 读取并校验 agc-apiclient.json：必填字段齐全、域名按 region 映射
+ * （显式配置的 api_domain/storage_domain 优先）。失败返回原因，不抛异常。
+ *
+ * @param configPath    agc-apiclient.json 绝对路径
+ * @param tokenCacheDir token 缓存目录覆盖（测试用）
+ * @returns              成功返回完整凭证；失败返回原因
+ */
+export declare function loadAgcCredentials(configPath: string, tokenCacheDir?: string): LoadCredentialsResult;
+export interface AgcUploader {
+    /**
+     * 上传一次触发的两个文件（归档包 + 快照）到
+     * YYYYMMDD/<projectName>-<sessionId>/<agentName>-<trigger>-v<n>.tar.gz|.json，
+     * 两者都成功才算成功；任一失败返回该失败（整任务由队列重试）。
+     *
+     * @param uploadPackage 归档产物（含双文件与路径元数据）
+     */
+    uploadPackage(uploadPackage: UploadPackage): Promise<UploadOutcome>;
+}
+/**
+ * 创建 AGC 上传器（token 自动获取与缓存 + 流式 PUT）。
+ *
+ * @param credentials 已解析的凭证
+ */
+export declare function createAgcUploader(credentials: AgcCredentials): AgcUploader;
+/**
+ * 缩写 agent 名用于云端路径段：按 "-" 分段取各段首字母（harmonyos-convert→hc），
+ * 单段名取前 3 字符（explore→exp），空名兜底 agent。
+ *
+ * @param agentName 触发时会话的 agent 名
+ * @returns          缩写后的安全路径段
+ */
+export declare function abbreviateAgentName(agentName: string): string;
+/** 归档包云端对象完整路径（上传成功日志用） */
+export declare function remoteArchiveKey(uploadPackage: UploadPackage): string;