feat(core): add typed policy and integrity contracts
This commit is contained in:
@@ -0,0 +1,55 @@
|
||||
/** Provider-neutral progress observation for one ordinary request. */
|
||||
export interface ProgressUpdate {
|
||||
readonly phase: string;
|
||||
readonly completed: number;
|
||||
readonly total: number | null;
|
||||
readonly message: string;
|
||||
readonly terminal?: boolean;
|
||||
}
|
||||
|
||||
/** Progress boundary shared by CLI, MCP, application workflows, and providers. */
|
||||
export interface ProgressReporter {
|
||||
report(update: ProgressUpdate): Promise<void>;
|
||||
}
|
||||
|
||||
/** Create a monotonic, rate-bounded reporter around a surface-specific sink. */
|
||||
export const createProgressReporter = (
|
||||
sink: (
|
||||
update: ProgressUpdate & { readonly sequence: number },
|
||||
) => Promise<void>,
|
||||
options: {
|
||||
readonly minimumIntervalMs?: number;
|
||||
readonly now?: () => number;
|
||||
} = {},
|
||||
): ProgressReporter => {
|
||||
const minimumIntervalMs = options.minimumIntervalMs ?? 100;
|
||||
const now = options.now ?? Date.now;
|
||||
let lastCompleted = -1;
|
||||
let lastSentAt = Number.NEGATIVE_INFINITY;
|
||||
let sequence = 0;
|
||||
return {
|
||||
async report(update) {
|
||||
if (!Number.isFinite(update.completed) || update.completed < 0)
|
||||
throw new TypeError("Progress completed must be a nonnegative number");
|
||||
if (update.total !== null && update.total < update.completed)
|
||||
throw new TypeError("Progress total cannot be less than completed");
|
||||
if (update.completed < lastCompleted)
|
||||
throw new TypeError("Progress cannot move backwards");
|
||||
lastCompleted = update.completed;
|
||||
const observedAt = now();
|
||||
if (
|
||||
update.terminal !== true &&
|
||||
observedAt - lastSentAt < minimumIntervalMs
|
||||
)
|
||||
return;
|
||||
lastSentAt = observedAt;
|
||||
sequence += 1;
|
||||
await sink({ ...update, sequence });
|
||||
},
|
||||
};
|
||||
};
|
||||
|
||||
/** Surface that deliberately ignores progress while preserving one workflow API. */
|
||||
export const silentProgressReporter: ProgressReporter = {
|
||||
report: () => Promise.resolve(),
|
||||
};
|
||||
Reference in New Issue
Block a user