@bizagent/dsh 0.0.0-stage → 1.0.0

package/lib/config.d.ts

@@ -0,0 +1,56 @@
+import Schema from '@deepseek-ai/schemastery';
+import { type ContextBudget, type HomeAddress } from './domain.js';
+export interface LearningScheduleConfig {
+    home: string;
+    cron: string;
+    model: string;
+    provider?: string;
+    maxTokens?: number;
+    dailyRuns?: number;
+}
+export interface ResolvedLearningSchedule {
+    home: HomeAddress;
+    cron: string;
+    model: string;
+    provider?: string;
+    maxTokens?: number;
+    dailyRuns: number;
+}
+export interface Config {
+    homeRoot?: string;
+    defaultHome?: string;
+    defaultIdentity?: string;
+    autoCreateDefaultHome?: boolean;
+    workspaceHomes?: Record<string, string>;
+    identityMaxBytes?: number;
+    indexMaxBytes?: number;
+    learningCheckpointEnabled?: boolean;
+    learningSchedulerEnabled?: boolean;
+    learningSchedules?: LearningScheduleConfig[];
+    timeZone?: string;
+    owner?: string;
+}
+export declare const Config: Schema<Config>;
+export interface ResolvedConfig {
+    homeRoot: string;
+    defaultHome?: HomeAddress;
+    defaultIdentity?: string;
+    autoCreateDefaultHome: boolean;
+    workspaceHomes: ReadonlyArray<{
+        root: string;
+        address: HomeAddress;
+    }>;
+    budget: ContextBudget;
+    learningCheckpointEnabled: boolean;
+    learningSchedulerEnabled: boolean;
+    learningSchedules: ReadonlyArray<ResolvedLearningSchedule>;
+    timeZone: string;
+    owner: string;
+}
+export declare function resolveConfig(input?: Config): ResolvedConfig;
+/**
+ * `$BIZAGENT_HOME`, else `~/BizAgent`. Data written before the data root moved, at
+ * `$DSH_HOME/bizagent`, keeps being used until it is moved, so upgrading never hides it.
+ */
+export declare function defaultHomeRoot(): string;
+//# sourceMappingURL=config.d.ts.map

package/lib/config.js

@@ -0,0 +1,115 @@
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { isAbsolute, join, resolve } from 'node:path';
+import Schema from '@deepseek-ai/schemastery';
+import { parseHomeAddress } from './domain.js';
+import { hostTimeZone, nextCronAt, resolveTimeZone } from './cron.js';
+import { isLocalUserId, localOwnerId } from './local-owner.js';
+export const Config = Schema.object({
+    homeRoot: Schema.string().description('BizAgent data root: your personal Homes, and your organizations under orgs/. '
+        + 'Defaults to $BIZAGENT_HOME or ~/BizAgent.'),
+    defaultHome: Schema.string().default('personal:default'),
+    defaultIdentity: Schema.string(),
+    autoCreateDefaultHome: Schema.boolean().default(true),
+    workspaceHomes: Schema.dict(Schema.string()).default({}),
+    identityMaxBytes: Schema.number().step(1).min(256).default(6144),
+    indexMaxBytes: Schema.number().step(1).min(512).default(16384),
+    learningCheckpointEnabled: Schema.boolean().default(true),
+    learningSchedulerEnabled: Schema.boolean().default(false).description('Run host-configured learning schedules every 30 seconds. Enable on exactly one host process for this profile.'),
+    learningSchedules: Schema.array(Schema.object({
+        home: Schema.string(), cron: Schema.string(), model: Schema.string(),
+        provider: Schema.string(), maxTokens: Schema.number().step(1).min(1),
+        dailyRuns: Schema.number().step(1).min(1).max(4).default(1),
+    })).default([]),
+    timeZone: Schema.string().description('IANA time zone for cron schedules and daily run limits. Defaults to the host time zone.'),
+    owner: Schema.string().description('Person who owns Homes this host creates (the default Home, onboarding organizations, and Homes created in the UI). '
+        + 'Defaults to $BIZAGENT_LOCAL_HUMAN_ID or the operating system user name.'),
+});
+export function resolveConfig(input = {}) {
+    const homeRoot = resolve(expandHome(input.homeRoot?.trim() || defaultHomeRoot()));
+    const defaultHome = input.defaultHome?.trim()
+        ? parseHomeAddress(input.defaultHome.trim())
+        : undefined;
+    const workspaceHomes = Object.entries(input.workspaceHomes ?? {})
+        .map(([root, address]) => ({
+        root: resolve(expandHome(root)),
+        address: parseHomeAddress(address),
+    }))
+        .sort((a, b) => b.root.length - a.root.length);
+    const identityMaxBytes = input.identityMaxBytes ?? 6144;
+    const indexMaxBytes = input.indexMaxBytes ?? 16384;
+    if (!Number.isSafeInteger(identityMaxBytes) || identityMaxBytes < 256) {
+        throw new TypeError('identityMaxBytes must be an integer >= 256');
+    }
+    if (!Number.isSafeInteger(indexMaxBytes) || indexMaxBytes < 512) {
+        throw new TypeError('indexMaxBytes must be an integer >= 512');
+    }
+    const timeZone = input.timeZone?.trim() ? resolveTimeZone(input.timeZone) : hostTimeZone();
+    const owner = input.owner?.trim() || localOwnerId();
+    if (!isLocalUserId(owner))
+        throw new TypeError('owner must use 1-100 letters, numbers, dots, underscores, or hyphens');
+    const learningSchedules = (input.learningSchedules ?? []).map(item => {
+        const home = parseHomeAddress(item.home);
+        const cron = item.cron.trim();
+        nextCronAt(cron, Date.now());
+        const model = item.model.trim();
+        const provider = item.provider?.trim();
+        const dailyRuns = item.dailyRuns ?? 1;
+        if (!model || model.length > 200)
+            throw new TypeError('learning schedule model must contain 1 to 200 characters');
+        if (provider !== undefined && (!provider || provider.length > 200)) {
+            throw new TypeError('learning schedule provider must contain 1 to 200 characters');
+        }
+        if (!Number.isSafeInteger(dailyRuns) || dailyRuns < 1 || dailyRuns > 4) {
+            throw new TypeError('learning schedule dailyRuns must be between 1 and 4');
+        }
+        if (item.maxTokens !== undefined && (!Number.isSafeInteger(item.maxTokens) || item.maxTokens < 1)) {
+            throw new TypeError('learning schedule maxTokens must be a positive integer');
+        }
+        if (workspaceHomes.filter(mapping => mapping.address === home).length !== 1) {
+            throw new TypeError(`learning schedule Home ${home} requires exactly one mapped Workspace`);
+        }
+        return { home, cron, model, dailyRuns,
+            ...(provider ? { provider } : {}),
+            ...(item.maxTokens ? { maxTokens: item.maxTokens } : {}),
+        };
+    });
+    if (new Set(learningSchedules.map(item => item.home)).size !== learningSchedules.length) {
+        throw new TypeError('learning schedules require distinct Homes');
+    }
+    return {
+        homeRoot,
+        ...(defaultHome !== undefined ? { defaultHome } : {}),
+        ...(input.defaultIdentity?.trim() ? { defaultIdentity: input.defaultIdentity.trim() } : {}),
+        autoCreateDefaultHome: input.autoCreateDefaultHome ?? true,
+        workspaceHomes,
+        budget: { identityMaxBytes, indexMaxBytes },
+        learningCheckpointEnabled: input.learningCheckpointEnabled ?? true,
+        learningSchedulerEnabled: input.learningSchedulerEnabled ?? false,
+        learningSchedules,
+        timeZone,
+        owner,
+    };
+}
+/**
+ * `$BIZAGENT_HOME`, else `~/BizAgent`. Data written before the data root moved, at
+ * `$DSH_HOME/bizagent`, keeps being used until it is moved, so upgrading never hides it.
+ */
+export function defaultHomeRoot() {
+    const configured = process.env['BIZAGENT_HOME']?.trim();
+    if (configured)
+        return expandHome(configured);
+    const current = join(homedir(), 'BizAgent');
+    const legacy = join(process.env['DSH_HOME']?.trim() || join(homedir(), '.dsh'), 'bizagent');
+    return !existsSync(current) && existsSync(join(legacy, 'directory.yaml')) ? legacy : current;
+}
+function expandHome(path) {
+    if (path === '~')
+        return homedir();
+    if (path.startsWith('~/') || path.startsWith('~\\'))
+        return join(homedir(), path.slice(2));
+    if (isAbsolute(path))
+        return path;
+    return resolve(path);
+}
+//# sourceMappingURL=config.js.map

package/lib/cron.d.ts

@@ -0,0 +1,9 @@
+/** The host's IANA time zone, or UTC when the runtime cannot report one. */
+export declare function hostTimeZone(): string;
+/** Validate an IANA time zone name and return its canonical spelling. */
+export declare function resolveTimeZone(timeZone: string): string;
+/** Calendar day (YYYY-MM-DD) of an instant in the given time zone. */
+export declare function zonedDay(time: number, timeZone?: string): string;
+/** Next five-field cron occurrence in `timeZone`, strictly after `after`. */
+export declare function nextCronAt(cron: string, after: number, timeZone?: string): number;
+//# sourceMappingURL=cron.d.ts.map

package/lib/cron.js

@@ -0,0 +1,127 @@
+const MINUTE = 60_000;
+const MONTHS = ['JAN', 'FEB', 'MAR', 'APR', 'MAY', 'JUN', 'JUL', 'AUG', 'SEP', 'OCT', 'NOV', 'DEC'];
+const DAYS = ['SUN', 'MON', 'TUE', 'WED', 'THU', 'FRI', 'SAT'];
+const formatters = new Map();
+/** The host's IANA time zone, or UTC when the runtime cannot report one. */
+export function hostTimeZone() {
+    try {
+        return Intl.DateTimeFormat().resolvedOptions().timeZone || 'UTC';
+    }
+    catch {
+        return 'UTC';
+    }
+}
+/** Validate an IANA time zone name and return its canonical spelling. */
+export function resolveTimeZone(timeZone) {
+    const name = timeZone.trim();
+    if (!name)
+        throw new TypeError('timeZone must name an IANA time zone');
+    try {
+        return new Intl.DateTimeFormat('en-US', { timeZone: name }).resolvedOptions().timeZone;
+    }
+    catch {
+        throw new TypeError(`unknown timeZone: ${timeZone}`);
+    }
+}
+/** Calendar day (YYYY-MM-DD) of an instant in the given time zone. */
+export function zonedDay(time, timeZone = 'UTC') {
+    const clock = wallClock(time, timeZone);
+    return `${clock.year}-${String(clock.month).padStart(2, '0')}-${String(clock.day).padStart(2, '0')}`;
+}
+/** Next five-field cron occurrence in `timeZone`, strictly after `after`. */
+export function nextCronAt(cron, after, timeZone = 'UTC') {
+    if (!Number.isSafeInteger(after) || after < 0)
+        throw new Error('invalid cron clock');
+    const fields = cron.trim().split(/\s+/);
+    if (fields.length !== 5)
+        throw new Error('cron requires five fields');
+    const [minute, hour, day, month, weekday] = [
+        parseField(fields[0], 0, 59), parseField(fields[1], 0, 23),
+        parseField(fields[2], 1, 31), parseField(fields[3], 1, 12, MONTHS),
+        parseField(fields[4], 0, 7, DAYS),
+    ];
+    const limit = after + 8 * 366 * 24 * 60 * MINUTE;
+    let candidate = Math.floor(after / MINUTE) * MINUTE + MINUTE;
+    while (candidate < limit) {
+        const local = wallClock(candidate, timeZone);
+        const dateMatch = day.wildcard && weekday.wildcard ? true
+            : day.wildcard ? weekday.values.has(local.weekday)
+                : weekday.wildcard ? day.values.has(local.day)
+                    : day.values.has(local.day) || weekday.values.has(local.weekday);
+        // Skip to the next local hour when the date or hour cannot match. Offset changes happen on
+        // hour or half-hour boundaries, so this never steps over a valid minute.
+        if (!month.values.has(local.month) || !dateMatch || !hour.values.has(local.hour)) {
+            candidate += (60 - local.minute) * MINUTE;
+            continue;
+        }
+        if (minute.values.has(local.minute))
+            return candidate;
+        candidate += MINUTE;
+    }
+    throw new Error('cron has no occurrence within eight years');
+}
+function wallClock(time, timeZone) {
+    if (timeZone === 'UTC') {
+        const date = new Date(time);
+        return { year: date.getUTCFullYear(), month: date.getUTCMonth() + 1, day: date.getUTCDate(),
+            weekday: date.getUTCDay(), hour: date.getUTCHours(), minute: date.getUTCMinutes() };
+    }
+    let formatter = formatters.get(timeZone);
+    if (formatter === undefined) {
+        formatter = new Intl.DateTimeFormat('en-US', { timeZone, hourCycle: 'h23', year: 'numeric',
+            month: 'numeric', day: 'numeric', weekday: 'short', hour: 'numeric', minute: 'numeric' });
+        formatters.set(timeZone, formatter);
+    }
+    const parts = {};
+    for (const part of formatter.formatToParts(time))
+        parts[part.type] = part.value;
+    return { year: Number(parts['year']), month: Number(parts['month']), day: Number(parts['day']),
+        weekday: DAYS.indexOf(String(parts['weekday']).toUpperCase()),
+        hour: Number(parts['hour']), minute: Number(parts['minute']) };
+}
+function parseField(text, min, max, names) {
+    const wildcard = text === '*' || text === '?';
+    const values = new Set();
+    for (const entry of text.toUpperCase().split(',')) {
+        const match = /^([^/]+)(?:\/(\d+))?$/.exec(entry);
+        if (!match)
+            throw new Error(`invalid cron field: ${text}`);
+        const [, base, stepText] = match;
+        const step = stepText === undefined ? 1 : Number(stepText);
+        if (!Number.isSafeInteger(step) || step < 1)
+            throw new Error(`invalid cron step: ${text}`);
+        let start;
+        let end;
+        if (base === '*' || base === '?') {
+            start = min;
+            end = max;
+        }
+        else if (base.includes('-')) {
+            const parts = base.split('-');
+            if (parts.length !== 2)
+                throw new Error(`invalid cron range: ${text}`);
+            start = fieldNumber(parts[0], min, max, names);
+            end = fieldNumber(parts[1], min, max, names);
+        }
+        else {
+            start = fieldNumber(base, min, max, names);
+            end = stepText === undefined ? start : max;
+        }
+        if (start > end)
+            throw new Error(`reversed cron range: ${text}`);
+        for (let value = start; value <= end; value += step)
+            values.add(max === 7 && value === 7 ? 0 : value);
+    }
+    if (values.size === 0)
+        throw new Error(`empty cron field: ${text}`);
+    return { values, wildcard };
+}
+function fieldNumber(text, min, max, names) {
+    const named = names?.indexOf(text);
+    const value = named !== undefined && named >= 0 ? named + (max === 12 ? 1 : 0) : Number(text);
+    if (!Number.isSafeInteger(value) || value < min || value > max || text.trim() === '') {
+        throw new Error(`invalid cron value: ${text}`);
+    }
+    return value;
+}
+//# sourceMappingURL=cron.js.map