@withtruing/companion 0.0.0-stage → 0.13.1

package/dist/text-model.js

@@ -0,0 +1,121 @@
+const PURPOSE_ERRORS = {
+    'verify_module:file_select': {
+        refusal: null,
+        empty: 'Could not pick files to check (no text in the file-select response).',
+    },
+    'verify_module:judge': {
+        refusal: 'The model declined to check this module.',
+        empty: 'No verdict returned.',
+    },
+    'generate_spec_batch:file_select': {
+        refusal: null,
+        empty: 'Could not pick files for this batch (no text in the file-select response).',
+    },
+    'generate_spec_batch:write': {
+        refusal: 'The model declined to write specs for this batch.',
+        empty: 'No specs returned.',
+    },
+    propose_skeleton: {
+        refusal: 'The model declined this request.',
+        empty: 'No result returned.',
+    },
+    propose_new_capabilities: {
+        refusal: 'The model declined this request.',
+        empty: 'No result returned.',
+    },
+    design_prompt: {
+        refusal: 'The model declined to write a design prompt.',
+        empty: 'No design prompt returned.',
+    },
+    analyse_shipment: {
+        refusal: 'The model declined to analyse this shipment.',
+        empty: 'No drift analysis returned.',
+    },
+    generic: {
+        refusal: 'The model declined this request.',
+        empty: 'No result returned.',
+    },
+};
+/** Server-side refusal fallback: on a policy decline the API re-runs the request on Anthropic's
+ * recommended substitute inside the same call. The scalar "default" form needs exactly this header
+ * (the array form is gated by -2026-06-01; pairing either header with the other form is a 400). */
+const FALLBACK_BETA = 'server-side-fallback-2026-07-01';
+/** SDK 0.111 types `fallbacks` as the array form only; the API also takes the scalar "default". */
+const DEFAULT_FALLBACKS = 'default';
+/** Every API-key call goes through here, so each one carries the refusal fallback. */
+export function streamWithFallback(client, params) {
+    return client.beta.messages.stream({ ...params, betas: [FALLBACK_BETA], fallbacks: DEFAULT_FALLBACKS });
+}
+/** stop_reason 'refusal' — after the fallback, the whole chain declined. Thrown before content is
+ * read, so a partial or empty reply is never parsed as a result. */
+export class ModelRefusalError extends Error {
+    category;
+    constructor(message, category = null) {
+        super(message);
+        this.name = 'ModelRefusalError';
+        this.category = category;
+    }
+}
+/** The reply text once a refusal is ruled out. A mid-output fallback continues the declined
+ * model's partial text in a later block, so every text block is joined; null when there is none. */
+export function replyText(message, refusal) {
+    if (message.stop_reason === 'refusal')
+        throw new ModelRefusalError(refusal, message.stop_details?.category ?? null);
+    const text = message.content.map((block) => (block.type === 'text' ? block.text : '')).join('');
+    return text || null;
+}
+function usageRecord(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return null;
+    const usage = {};
+    for (const [key, candidate] of Object.entries(value)) {
+        if (typeof candidate === 'number' && Number.isFinite(candidate))
+            usage[key] = candidate;
+    }
+    return Object.keys(usage).length > 0 ? usage : null;
+}
+/** Adapt the existing Anthropic transport without changing any request field or content-block
+ * ordering used by the API-key backend. */
+export function anthropicTextModel(client) {
+    return async (request) => {
+        const blocks = [];
+        if (request.documentBase64) {
+            blocks.push({
+                type: 'document',
+                source: { type: 'base64', media_type: 'application/pdf', data: request.documentBase64 },
+            });
+        }
+        if (request.stableText) {
+            blocks.push({
+                type: 'text',
+                text: request.stableText,
+                cache_control: { type: 'ephemeral' },
+            });
+        }
+        blocks.push({ type: 'text', text: request.text });
+        const content = request.purpose.endsWith(':file_select') && blocks.length === 1 && blocks[0].type === 'text'
+            ? blocks[0].text
+            : blocks;
+        const stream = streamWithFallback(client, {
+            model: request.model,
+            max_tokens: request.maxTokens,
+            thinking: { type: 'adaptive' },
+            output_config: request.schema
+                ? { effort: request.effort, format: { type: 'json_schema', schema: request.schema } }
+                : { effort: request.effort },
+            system: request.system,
+            messages: [{ role: 'user', content }],
+        });
+        const message = await stream.finalMessage();
+        const errors = PURPOSE_ERRORS[request.purpose] ?? {
+            refusal: `The model declined the ${request.purpose} call.`,
+            empty: `The ${request.purpose} call returned no text.`,
+        };
+        // A purpose with no refusal wording of its own still fails as a refusal, under its empty-reply
+        // wording — never by reading whatever partial text the declined attempt left behind.
+        const text = replyText(message, errors.refusal ?? errors.empty);
+        if (!text)
+            throw new Error(errors.empty);
+        return { text, usage: usageRecord(message.usage) };
+    };
+}

package/dist/types.js

@@ -0,0 +1,11 @@
+/**
+ * The wire contract with the Console's /api/companion/* routes. Deliberately NOT imported from
+ * the parent repo's server/model-caller.ts or shared/types.ts — this package is meant to be
+ * independently npm-publishable (see the local-companion plan's Section 7), so it defines its
+ * own copy of the shapes it needs rather than reaching across a package boundary that won't
+ * exist once this ships standalone. The pure reader-result checks are vendored byte-for-byte in
+ * reader-result-contract.ts from the server's canonical copy; keep the remaining shapes in sync
+ * with server/model-caller.ts's ModelTaskSpec, server/store.ts's LocalTaskRow, and the named
+ * Stage 2 wire schemas by hand.
+ */
+export {};

package/dist/usage-limit.js

@@ -0,0 +1,130 @@
+const FALLBACK_PAUSE_MS = 30 * 60_000;
+const RESET_GRACE_MS = 2 * 60_000;
+export function isUsageLimitError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return /you(?:'|\u2019)ve hit your (?:session|usage|rate) limit\b/i.test(message)
+        || /(?:usage limit reached|rate limit exceeded|quota exceeded)\b/i.test(message);
+}
+function zonedParts(date, timeZone) {
+    const parts = new Intl.DateTimeFormat('en-CA', {
+        timeZone,
+        year: 'numeric',
+        month: '2-digit',
+        day: '2-digit',
+        hour: '2-digit',
+        minute: '2-digit',
+        second: '2-digit',
+        hourCycle: 'h23',
+    }).formatToParts(date);
+    return Object.fromEntries(parts
+        .filter((part) => part.type !== 'literal')
+        .map((part) => [part.type, Number(part.value)]));
+}
+function zonedTimeToDate(date, time, timeZone) {
+    const target = Date.UTC(date.year, date.month - 1, date.day, time.hour, time.minute);
+    let candidate = target;
+    try {
+        // Intl exposes offsets only indirectly. Iterating the difference between the desired wall
+        // clock and the wall clock at the candidate converges for ordinary times and across DST.
+        for (let iteration = 0; iteration < 4; iteration++) {
+            const observed = zonedParts(new Date(candidate), timeZone);
+            const observedAsUtc = Date.UTC(observed.year, observed.month - 1, observed.day, observed.hour, observed.minute, observed.second);
+            const adjustment = target - observedAsUtc;
+            candidate += adjustment;
+            if (adjustment === 0)
+                break;
+        }
+        const result = new Date(candidate);
+        const verified = zonedParts(result, timeZone);
+        return verified.year === date.year
+            && verified.month === date.month
+            && verified.day === date.day
+            && verified.hour === time.hour
+            && verified.minute === time.minute
+            ? result
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+function addLocalDays(date, days) {
+    const shifted = new Date(Date.UTC(date.year, date.month - 1, date.day + days));
+    return {
+        year: shifted.getUTCFullYear(),
+        month: shifted.getUTCMonth() + 1,
+        day: shifted.getUTCDate(),
+    };
+}
+/** Parse the next reset instant named by a CLI usage-limit message. */
+export function parseUsageLimitReset(message, now = new Date(), defaultTimeZone = Intl.DateTimeFormat().resolvedOptions().timeZone) {
+    const match = /\bresets?\s+(?:(today|tomorrow)\s+)?(\d{1,2})(?::(\d{2}))?\s*(a\.?m\.?|p\.?m\.?)?\s*(?:\(([^)]+)\))?/i.exec(message);
+    if (!match)
+        return null;
+    const meridiem = match[4]?.replace(/\./g, '').toLowerCase();
+    const parsedHour = Number(match[2]);
+    const minute = match[3] === undefined ? 0 : Number(match[3]);
+    if (!Number.isInteger(parsedHour) || !Number.isInteger(minute) || minute > 59)
+        return null;
+    if (meridiem ? parsedHour < 1 || parsedHour > 12 : parsedHour > 23)
+        return null;
+    const hour = meridiem === 'am'
+        ? parsedHour % 12
+        : meridiem === 'pm'
+            ? (parsedHour % 12) + 12
+            : parsedHour;
+    const timeZone = match[5]?.trim() || defaultTimeZone;
+    let today;
+    try {
+        const parts = zonedParts(now, timeZone);
+        today = { year: parts.year, month: parts.month, day: parts.day };
+    }
+    catch {
+        return null;
+    }
+    const qualifier = match[1]?.toLowerCase();
+    let date = addLocalDays(today, qualifier === 'tomorrow' ? 1 : 0);
+    let reset = zonedTimeToDate(date, { hour, minute }, timeZone);
+    if (!reset)
+        return null;
+    if (qualifier !== 'tomorrow' && reset.getTime() <= now.getTime()) {
+        date = addLocalDays(date, 1);
+        reset = zonedTimeToDate(date, { hour, minute }, timeZone);
+    }
+    return reset;
+}
+export class UsageLimitPause {
+    output;
+    defaultTimeZone;
+    pausedUntilMs = null;
+    resumeWithProbe = false;
+    constructor(output = console, defaultTimeZone = Intl.DateTimeFormat().resolvedOptions().timeZone) {
+        this.output = output;
+        this.defaultTimeZone = defaultTimeZone;
+    }
+    get pausedUntil() {
+        return this.pausedUntilMs === null ? null : new Date(this.pausedUntilMs);
+    }
+    pause(message, now = new Date()) {
+        const reset = parseUsageLimitReset(message, now, this.defaultTimeZone);
+        this.pausedUntilMs = reset
+            ? reset.getTime() + RESET_GRACE_MS
+            : now.getTime() + FALLBACK_PAUSE_MS;
+        this.resumeWithProbe = reset === null;
+        this.output.log(`Usage limit reached \u2014 pausing until ${new Date(this.pausedUntilMs).toISOString()} (no work will be claimed)`);
+    }
+    /** Number of actual jobs this poll cycle may claim. Null means there is no usage-limit cap. */
+    claimLimit(now = new Date()) {
+        if (this.pausedUntilMs === null)
+            return null;
+        if (now.getTime() < this.pausedUntilMs)
+            return 0;
+        const probe = this.resumeWithProbe;
+        this.pausedUntilMs = null;
+        this.resumeWithProbe = false;
+        this.output.log(probe
+            ? `[${now.toISOString()}] Usage limit pause ended \u2014 trying one probe claim.`
+            : `[${now.toISOString()}] Usage limit pause ended \u2014 resuming work.`);
+        return probe ? 1 : null;
+    }
+}

package/package.json

@@ -1,6 +1,50 @@
 {
   "name": "@withtruing/companion",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.13.1",
+  "description": "The Truing companion: reads your code and runs AI on your own computer, for Truing.",
+  "type": "module",
+  "license": "MIT",
+  "bin": {
+    "truing": "dist/cli.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "dev": "tsx src/cli.ts",
+    "test": "tsx --test --test-concurrency=1 test/*.test.ts"
+  },
+  "keywords": [
+    "cli",
+    "ai",
+    "anthropic",
+    "claude",
+    "companion",
+    "byok",
+    "byos",
+    "truing"
+  ],
+  "homepage": "https://app.withtruing.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fynchconsulting/product-console.git",
+    "directory": "companion"
+  },
+  "dependencies": {
+    "@anthropic-ai/sdk": "^0.111.0",
+    "cross-spawn": "^7.0.6",
+    "typescript": "5.9.3"
+  },
+  "devDependencies": {
+    "@types/cross-spawn": "^6.0.6",
+    "@types/node": "^24.10.1",
+    "tsx": "^4.20.6"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}