@causyne/agent 0.0.0-stage → 1.10.0

package/src/uncertainty.js

@@ -0,0 +1,271 @@
+import { failureClass } from './planCache.js';
+
+// Step-level uncertainty, computed from signals the loop already holds.
+//
+// WHAT THIS IS NOT, AND WHY.
+//
+// The research spec asked for CATTS-style gating: sample N candidate actions,
+// measure entropy and the top-1/top-2 margin across them, and escalate when the
+// samples disagree. Two findings killed that design.
+//
+//   1. The CATTS and OPPO papers are NOT in the research corpus. Asked
+//      directly, it reported their absence three times. The spec cited them
+//      second-hand, so their thresholds were never available to us.
+//   2. More decisively: without token logprobs, every method in that family
+//      measures disagreement by SAMPLING N completions. Causyne is BYOK across
+//      ten providers and several expose no logprobs at all. Sampling N times to
+//      decide whether to spend more is self-defeating — the gate would cost
+//      more than the thing it gates.
+//
+// Asked which substitutes exist when logprobs are unavailable, the corpus named
+// four: majority voting over N samples, an auxiliary verifier model, cross-tool
+// execution matching, and verbalized self-critique. The first two each cost an
+// extra model call. **The last two do not**, and they are what this module is
+// built from, together with execution signals the loop already tracks for free.
+//
+// WHAT THE CORPUS THEN CONFIRMED (research round 3, questions A1-A7).
+//
+// "Dynamic Adaptive Reasoning: Intent-Aware Scheduling" (IARS) detects its
+// reasoning states — Exploring, Confirming, Stuck/Ambiguous, Near-Answer — with
+// one of two pipelines: a small trained classifier, OR **a text-based heuristic
+// of keyword matching plus structural repetition analysis**, run as a parallel
+// stream analyser with negligible cost and no logprobs. That second pipeline is
+// this module. The thrash detector below is its "structural repetition"; the
+// hedge patterns are its "keyword matching". So this is an implementation of a
+// published detector, not an extrapolation.
+//
+// IARS issues four directives — [DEEPER_THINK], [STREAMLINE_THINK],
+// [CONCLUDE_NOW], [RETRY_SUBPROBLEM] — and couples them to decoding:
+// DEEPER_THINK raises temperature to widen the search; CONCLUDE_NOW drops into
+// fast decoding. The paper states the DIRECTION of those changes and NOT the
+// magnitudes ("present, but not stated"). The delta below is therefore ours.
+//
+// Two things the corpus ruled OUT, so nobody re-proposes them:
+//   * REVERSE ("Generate, but Verify") gates on P(</UN>) > tau with tau = 0.003
+//     (LLaVA) / 0.01 (Qwen2.5-VL). It needs a model FINE-TUNED to emit that
+//     token — unavailable over BYOK — and its measured overhead is 3.05x tokens.
+//     A gate that triples the bill is the failure this module exists to avoid.
+//   * Verbalized self-confidence (a model rating its own confidence) is NOT
+//     evaluated or calibrated anywhere in the corpus. The hedge patterns here
+//     are used as IARS-style Stuck/Ambiguous keyword detection, never as a
+//     calibrated confidence score, and they cannot cross the gate alone.
+//
+// HONEST LIMITS:
+//   * No single signal can move the score past the escalation threshold alone.
+//   * The WEIGHTS are engineering judgement, not published constants. The
+//     corpus validates the SIGNALS (IARS, OBLIVION's query-to-buffer cosine
+//     similarity) but publishes no weights for combining them. They are named
+//     constants so measured values can replace them without touching logic.
+
+/**
+ * @typedef {Object} StepSignals
+ * @property {number}  [consecutiveFailures]  Failures in a row, from the loop.
+ * @property {any}     [lastResult]           The previous tool result, if any.
+ * @property {string}  [lastTool]             Name of the previous tool.
+ * @property {string}  [pendingTool]          The tool about to be called.
+ * @property {string[]}[recentTools]          Recent tool names, oldest first.
+ * @property {number}  [planSimilarity]       0..1 plan-cache match, if any.
+ * @property {number}  [lessonSimilarity]     0..1 Cortex retrieval match, if any.
+ * @property {string}  [assistantText]        The model's own last message.
+ * @property {number}  [logprobMargin]        top1-top2 in nats, when a provider exposes it.
+ * @property {boolean} [vfePlateau]           Whether variational free energy has plateaued.
+ */
+
+/**
+ * @typedef {Object} Assessment
+ * @property {number}   uncertainty  0 (settled) .. 1 (lost).
+ * @property {'confident'|'contested'|'stuck'} level
+ * @property {string[]} signals      Which contributors fired, for the audit trail.
+ * @property {string}   directive    Prompt text to inject, or '' to stay silent.
+ * @property {number}   temperatureDelta  Added to the task temperature for this
+ *                      step. IARS couples its escalation directive to a wider
+ *                      search; the direction is the paper's, the magnitude is
+ *                      ours (see STUCK_TEMPERATURE_DELTA).
+ */
+
+/** Above this, the step is contested enough to be worth a reflection directive. */
+export const CONTESTED_AT = 0.45;
+
+/** Above this, the agent is not converging and should re-plan rather than retry. */
+export const STUCK_AT = 0.75;
+
+/**
+ * How much wider the search gets when the agent is stuck.
+ *
+ * IARS: [DEEPER_THINK] / [RETRY_SUBPROBLEM] raise decoding temperature to
+ * escape a local minimum. The paper gives the direction and no number
+ * ("present, but not stated"), so this value is unmeasured. Kept small: a
+ * stuck agent needs a different route, not a random one.
+ */
+export const STUCK_TEMPERATURE_DELTA = 0.2;
+
+/**
+ * No single signal may cross CONTESTED_AT alone.
+ *
+ * This is the rule that keeps a badly-calibrated signal from driving the gate.
+ * Verbalized confidence in particular is unreliable enough that acting on it by
+ * itself would fire reflection on ordinary hedging language.
+ */
+const MAX_SINGLE_CONTRIBUTION = 0.4;
+
+const WEIGHTS = {
+  consecutiveFailure: 0.25,  // per failure, capped below
+  // Weighted ABOVE a bare failure count on purpose. Three failures say
+  // "something is wrong"; a `not_found` class says WHAT — and a diagnosis is
+  // worth more than a symptom. With this at 0.15, three failures on a wrong
+  // route scored 0.60 and never reached the retry directive that exists for
+  // exactly that case.
+  hardFailureClass: 0.30,    // a failure that says the ROUTE is wrong
+  thrash: 0.30,              // the same tool three times running
+  vfePlateau: 0.35,          // Active Inference: error plateau with zero variance (stuck in local minimum)
+  noPriorArt: 0.05,          // nothing in plan cache or Cortex to lean on
+  hedging: 0.20,             // the model's own language says it is unsure
+  logprobMargin: 0.25        // only when a provider actually exposes it
+};
+
+/**
+ * Phrases in which a model reports its own uncertainty.
+ *
+ * Deliberately narrow. A broad list turns ordinary careful writing into a
+ * signal, and a gate that fires on caution is a gate that fires always.
+ * @type {RegExp}
+ */
+const HEDGE = /\b(i am not sure|i'm not sure|not certain|unclear (?:why|what|how)|might be|may be wrong|hard to tell|cannot determine|let me guess|assuming that|if that is the case|unsure)\b/i;
+
+/**
+ * Failure classes that mean the ROUTE is wrong rather than the moment.
+ *
+ * `network` and `rate_limited` are absent on purpose: retrying is the correct
+ * response to those, and treating them as uncertainty would trigger a re-plan
+ * for a problem that fixes itself.
+ * @type {ReadonlySet<string>}
+ */
+const ROUTE_IS_WRONG = new Set(['not_found', 'permission', 'invalid_args', 'syntax']);
+
+/**
+ * Is the agent calling the same tool over and over?
+ *
+ * Repetition is the cheapest honest uncertainty signal there is: a converging
+ * agent moves on. Three of the same in a row is the threshold because two is a
+ * legitimate read-then-write pair.
+ *
+ * @param   {string[]} recent
+ * @param   {string}   pending
+ * @returns {boolean}
+ */
+export function isThrashing(recent, pending) {
+  const tail = [...(recent || [])];
+  if (pending) tail.push(pending);
+  if (tail.length < 3) return false;
+  const last3 = tail.slice(-3);
+  return last3.every((t) => t && t === last3[0]);
+}
+
+/**
+ * Score a step before committing to it.
+ *
+ * Every input is something the loop already has. Nothing here calls a model,
+ * samples a completion, or touches the network — which is the entire point.
+ *
+ * @param   {StepSignals} signals
+ * @returns {Assessment}
+ */
+export function assessStep(signals = {}) {
+  const fired = [];
+  let score = 0;
+
+  /** Add a contributor, capped so no single one can decide the outcome. */
+  const add = (amount, name) => {
+    const capped = Math.min(amount, MAX_SINGLE_CONTRIBUTION);
+    if (capped <= 0) return;
+    score += capped;
+    fired.push(name);
+  };
+
+  const failures = Number(signals.consecutiveFailures) || 0;
+  if (failures > 0) add(Math.min(failures, 3) * WEIGHTS.consecutiveFailure, `failures:${failures}`);
+
+  if (signals.lastResult) {
+    const why = failureClass(signals.lastResult);
+    if (why && ROUTE_IS_WRONG.has(why)) add(WEIGHTS.hardFailureClass, `route_wrong:${why}`);
+  }
+
+  if (isThrashing(signals.recentTools, signals.pendingTool)) {
+    add(WEIGHTS.thrash, `thrash:${signals.pendingTool || 'repeat'}`);
+  }
+
+  if (signals.vfePlateau) {
+    add(WEIGHTS.vfePlateau, 'vfe_plateau');
+  }
+
+  const bestPrior = Math.max(Number(signals.planSimilarity) || 0, Number(signals.lessonSimilarity) || 0);
+  if (bestPrior === 0) add(WEIGHTS.noPriorArt, 'no_prior_art');
+
+  if (typeof signals.assistantText === 'string' && HEDGE.test(signals.assistantText)) {
+    add(WEIGHTS.hedging, 'model_hedged');
+  }
+
+  // Only when the provider genuinely reports it. A missing margin is NOT
+  // evidence of confidence, so its absence contributes nothing in either
+  // direction.
+  if (typeof signals.logprobMargin === 'number' && Number.isFinite(signals.logprobMargin)) {
+    if (signals.logprobMargin < 0.5) add(WEIGHTS.logprobMargin, 'logprob_margin_narrow');
+  }
+
+  const uncertainty = Math.min(1, score);
+  const level = uncertainty >= STUCK_AT ? 'stuck' : uncertainty >= CONTESTED_AT ? 'contested' : 'confident';
+
+  return {
+    uncertainty,
+    level,
+    signals: fired,
+    directive: directiveFor(level, fired),
+    temperatureDelta: level === 'stuck' ? STUCK_TEMPERATURE_DELTA : 0
+  };
+}
+
+/**
+ * What to say to the model, if anything.
+ *
+ * Returns '' for a confident step. That empty string is the whole economic
+ * argument: reflecting on every step is what the gating literature exists to
+ * prevent, and the directive costs tokens on every step it appears in.
+ *
+ * @param   {string}   level
+ * @param   {string[]} fired
+ * @returns {string}
+ */
+export function directiveFor(level, fired = []) {
+  if (level === 'confident') return '';
+
+  const because = fired.length ? ` (${fired.join(', ')})` : '';
+
+  if (level === 'stuck') {
+    // Paradigm shift: when VFE plateau occurs, standard re-planning isn't enough;
+    // the agent is stuck in an active-inference local minimum.
+    if (fired.includes('vfe_plateau')) {
+      return `[PARADIGM SHIFT REQUIRED — persistent error plateau with zero convergence${because}. `
+        + 'Do NOT retry previous step variations or tweak command arguments. '
+        + 'Invalidate your operational hypothesis, state in one line what fundamental assumption was wrong, '
+        + 'and switch to a completely different tool, perspective, or strategy.]';
+    }
+
+    // IARS separates [RETRY_SUBPROBLEM] from a full re-plan. A wrong ROUTE
+    // with no thrashing means this one sub-problem needs a different approach;
+    // thrashing means the plan itself is not converging.
+    const thrashing = fired.some((f) => f.startsWith('thrash:'));
+    if (!thrashing) {
+      return `[RETRY_SUBPROBLEM — the last approach to THIS step failed in a way that says the route was wrong${because}. `
+        + 'Keep the overall plan. Solve this one step by a different route. '
+        + 'If a tool reported "not found", that is evidence about the ROUTE, not proof the thing is absent.]';
+    }
+    return `[RE-PLAN — the last few steps are not converging${because}. `
+      + 'Do NOT retry the same route. State in one line what you now believe is actually true, '
+      + 'name the assumption that turned out to be wrong, and choose a different approach. '
+      + 'If a tool reported "not found", that is evidence about the ROUTE, not proof the thing is absent.]';
+  }
+
+  return `[CHECK YOURSELF — this step looks contested${because}. `
+    + 'Before calling the tool, say in one line what you expect it to return. '
+    + 'If the result contradicts that expectation, treat the expectation as the thing that was wrong.]';
+}

package/src/userSkills.js

@@ -0,0 +1,265 @@
+
+
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { causyneHome } from './utils/paths.js';
+
+// Bounds. Every one of these protects the context window, which is the resource
+// a skill library actually spends.
+export const MAX_USER_SKILLS = 200;
+export const MAX_SKILL_BYTES = 32 * 1024;
+export const MAX_DESCRIPTION = 400;
+
+// A skill id and a domain are path segments. Lowercase, digits and hyphens is
+// the whole alphabet — which makes traversal, drive letters, device names,
+// leading dots and spaces unrepresentable rather than merely filtered.
+const SEGMENT = /^[a-z0-9][a-z0-9-]{0,63}$/;
+
+// Windows reserves these as device names. A directory called `con` or `aux`
+// cannot be created there, and `nul` silently discards what is written to it —
+// so a skill named after one would work on the author's Mac and fail, or vanish,
+// for a Windows user. Vision section 3: never assume the developer's own OS.
+const RESERVED = new Set([
+  'con', 'prn', 'aux', 'nul',
+  ...Array.from({ length: 9 }, (_, index) => `com${index + 1}`),
+  ...Array.from({ length: 9 }, (_, index) => `lpt${index + 1}`)
+]);
+
+export function userSkillsRoot() {
+  return path.join(causyneHome(), 'skills');
+}
+
+/** Is this a usable path segment? Returns a reason when it is not. */
+export function validateSegment(value, what = 'name') {
+  const text = String(value == null ? '' : value);
+  if (!text) return `${what} is required`;
+  if (!SEGMENT.test(text)) {
+    return `${what} must be lowercase letters, digits and hyphens, starting with a letter or digit `
+      + `(got ${JSON.stringify(text.slice(0, 40))})`;
+  }
+  if (RESERVED.has(text)) {
+    return `${what} ${JSON.stringify(text)} is a reserved device name on Windows — `
+      + 'a skill by that name would fail there. Pick another.';
+  }
+  return null;
+}
+
+/**
+ * Read `domain` and `name` out of a `domain/name` id.
+ *
+ * Rejects anything with a different shape rather than guessing, because a
+ * guessed split is how a traversal segment reaches a join().
+ */
+export function parseSkillId(id) {
+  const parts = String(id == null ? '' : id).split('/');
+  if (parts.length !== 2) {
+    return { error: 'skill id must be "domain/name", for example team/release-checklist' };
+  }
+  const [domain, name] = parts;
+  const domainError = validateSegment(domain, 'domain');
+  if (domainError) return { error: domainError };
+  const nameError = validateSegment(name, 'skill name');
+  if (nameError) return { error: nameError };
+  return { domain, name };
+}
+
+/** Strip control characters and collapse a description onto one line. */
+function cleanDescription(value) {
+  return String(value == null ? '' : value)
+    // eslint-disable-next-line no-control-regex
+    .replace(/[\x00-\x1f\x7f]/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim()
+    .slice(0, MAX_DESCRIPTION);
+}
+
+/** Remove control bytes from a body while keeping newlines and tabs. */
+function cleanBody(value) {
+  // eslint-disable-next-line no-control-regex
+  return String(value == null ? '' : value).replace(/[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]/g, '');
+}
+
+function parseFrontmatter(content) {
+  const match = content.match(/^---\n([\s\S]*?)\n---/);
+  if (!match) return {};
+  const block = match[1];
+  const name = block.match(/^name:\s*(.+)$/m);
+  const description = block.match(/^description:\s*(.+)$/m);
+  return {
+    name: name ? name[1].trim() : '',
+    description: description ? description[1].trim() : ''
+  };
+}
+
+/**
+ * Every user skill on disk, validated.
+ *
+ * Never throws: a broken file is skipped and reported, because one bad skill
+ * must not stop a session from starting. Returns { skills, problems }.
+ */
+export function loadUserSkills(root = userSkillsRoot()) {
+  const skills = [];
+  const problems = [];
+
+  let domains;
+  try {
+    if (!fs.existsSync(root)) return { skills, problems };
+    domains = fs.readdirSync(root, { withFileTypes: true })
+      .filter((entry) => entry.isDirectory() && !entry.name.startsWith('.'))
+      .map((entry) => entry.name);
+  } catch (e) {
+    return { skills, problems: [`could not read ${root}: ${e.message}`] };
+  }
+
+  for (const domain of domains) {
+    if (validateSegment(domain, 'domain')) {
+      problems.push(`skipped domain ${JSON.stringify(domain)}: not a valid name`);
+      continue;
+    }
+    let names;
+    try {
+      names = fs.readdirSync(path.join(root, domain), { withFileTypes: true })
+        .filter((entry) => entry.isDirectory() && !entry.name.startsWith('.'))
+        .map((entry) => entry.name);
+    } catch (e) { continue; }
+
+    for (const name of names) {
+      if (skills.length >= MAX_USER_SKILLS) {
+        problems.push(`stopped at ${MAX_USER_SKILLS} skills — the rest were not loaded`);
+        return { skills, problems };
+      }
+      if (validateSegment(name, 'skill name')) {
+        problems.push(`skipped ${domain}/${name}: not a valid name`);
+        continue;
+      }
+
+      const file = path.join(root, domain, name, 'SKILL.md');
+      let content;
+      try {
+        // Refuse a symlink outright: it is the one way a file inside this
+        // directory can point at something outside it.
+        const stat = fs.lstatSync(file);
+        if (!stat.isFile()) { problems.push(`skipped ${domain}/${name}: not a regular file`); continue; }
+        if (stat.size > MAX_SKILL_BYTES) {
+          problems.push(`skipped ${domain}/${name}: ${(stat.size / 1024).toFixed(0)} KB exceeds the `
+            + `${MAX_SKILL_BYTES / 1024} KB limit — a skill this large would crowd out the task`);
+          continue;
+        }
+        content = fs.readFileSync(file, 'utf8');
+      } catch (e) { continue; }
+
+      const meta = parseFrontmatter(content);
+      const description = cleanDescription(meta.description);
+      if (!description) {
+        problems.push(`skipped ${domain}/${name}: no description in the frontmatter — `
+          + 'the description is how the agent decides when the skill applies');
+        continue;
+      }
+
+      skills.push({
+        domain,
+        id: name,
+        name: meta.name || name,
+        description,
+        content: cleanBody(content),
+        source: 'user',
+        path: file
+      });
+    }
+  }
+  return { skills, problems };
+}
+
+/** The starting point a new skill is written from. */
+export function skillTemplate(domain, name, description = '') {
+  const title = name.split('-').map((word) => word[0].toUpperCase() + word.slice(1)).join(' ');
+  return `---
+name: ${name}
+description: ${description || `TODO — one line: what this does, and WHEN to reach for it.`}
+---
+
+# ${title}
+
+## Workflow
+
+1. First step.
+   - What to do, and the detail that is easy to get wrong.
+   - **Done when:** something you can actually check.
+
+2. Second step.
+   - **Done when:** something you can actually check.
+
+## Verification
+
+- How to confirm the whole thing worked.
+`;
+}
+
+/**
+ * Write a user skill to disk.
+ *
+ * Refuses to overwrite unless asked, so neither a user nor an agent can silently
+ * replace a skill someone spent time on.
+ */
+export function writeUserSkill({ domain, name, content, overwrite = false }, root = userSkillsRoot()) {
+  const domainError = validateSegment(domain, 'domain');
+  if (domainError) return { ok: false, error: domainError };
+  const nameError = validateSegment(name, 'skill name');
+  if (nameError) return { ok: false, error: nameError };
+
+  const body = cleanBody(content);
+  if (Buffer.byteLength(body, 'utf8') > MAX_SKILL_BYTES) {
+    return { ok: false, error: `skill exceeds the ${MAX_SKILL_BYTES / 1024} KB limit` };
+  }
+
+  const meta = parseFrontmatter(body);
+  if (!cleanDescription(meta.description)) {
+    return {
+      ok: false,
+      error: "the frontmatter needs a `description:` line — it is what the agent reads to decide whether the skill applies, so a skill without one can never be selected"
+    };
+  }
+
+  const directory = path.join(root, domain, name);
+  const file = path.join(directory, 'SKILL.md');
+
+  // Belt and braces: the resolved path must still be inside the root after every
+  // segment has been joined. Validation above already makes this unreachable.
+  const resolvedRoot = path.resolve(root);
+  const resolvedFile = path.resolve(file);
+  if (resolvedFile !== resolvedRoot && !resolvedFile.startsWith(resolvedRoot + path.sep)) {
+    return { ok: false, error: 'refusing to write outside the skills directory' };
+  }
+
+  if (!overwrite && fs.existsSync(file)) {
+    return { ok: false, error: `${domain}/${name} already exists — pass overwrite to replace it` };
+  }
+
+  try {
+    fs.mkdirSync(directory, { recursive: true });
+    fs.writeFileSync(file, body, 'utf8');
+  } catch (e) {
+    return { ok: false, error: `could not write ${file}: ${e.message}` };
+  }
+  return { ok: true, path: file };
+}
+
+/** Remove a user skill. Compiled skills are not removable — they are the build. */
+export function deleteUserSkill(domain, name, root = userSkillsRoot()) {
+  const domainError = validateSegment(domain, 'domain');
+  if (domainError) return { ok: false, error: domainError };
+  const nameError = validateSegment(name, 'skill name');
+  if (nameError) return { ok: false, error: nameError };
+
+  const directory = path.join(root, domain, name);
+  if (!fs.existsSync(path.join(directory, 'SKILL.md'))) {
+    return { ok: false, error: `${domain}/${name} is not a user skill` };
+  }
+  try {
+    fs.rmSync(directory, { recursive: true, force: true });
+  } catch (e) {
+    return { ok: false, error: `could not remove ${directory}: ${e.message}` };
+  }
+  return { ok: true, path: directory };
+}

package/src/utils/inquirer.js

@@ -0,0 +1,12 @@
+import rawInquirer from 'inquirer';
+
+
+const inquirer = rawInquirer?.prompt
+  ? rawInquirer
+  : (rawInquirer?.default?.prompt
+    ? rawInquirer.default
+    : (rawInquirer?.default?.default?.prompt
+      ? rawInquirer.default.default
+      : rawInquirer));
+
+export default inquirer;

package/src/utils/paths.js

@@ -0,0 +1,37 @@
+import os from 'os';
+import path from 'path';
+
+/**
+ * Resolve a path the model supplied, expanding a leading `~`.
+ *
+ * WHY THIS EXISTS. `path.resolve('~/x')` does NOT expand the tilde — it treats
+ * `~` as an ordinary directory name and returns `<cwd>/~/x`. Models write `~/`
+ * constantly, because that is how paths are written everywhere they have ever
+ * read one, and because Causyne's own transcript SHOWS paths that way.
+ *
+ * It cost a real run: `view_image ~/Causyne/pen_cinematic/preview.png` failed in
+ * 17ms with "Image not found at /Users/example/project/~/project/..."
+ * on a file that existed — the agent had just rendered it and was trying to
+ * look at its own work, which is the one step that separates a good render from
+ * a bad one.
+ *
+ * @param   {string} input  A path, possibly starting with `~`.
+ * @returns {string}        An absolute path.
+ */
+export function resolveUserPath(input) {
+  const raw = String(input ?? '').trim();
+  if (raw === '~') return os.homedir();
+  if (raw.startsWith('~/') || raw.startsWith('~\\')) {
+    return path.resolve(path.join(os.homedir(), raw.slice(2)));
+  }
+  return path.resolve(raw);
+}
+
+
+const STATE_ROOT = process.env.CAUSYNE_HOME && String(process.env.CAUSYNE_HOME).trim()
+  ? path.resolve(String(process.env.CAUSYNE_HOME).trim())
+  : path.join(os.homedir(), '.causyne');
+
+export function causyneHome() {
+  return STATE_ROOT;
+}

package/src/version.js

@@ -0,0 +1,38 @@
+import fs from 'fs';
+import path from 'path';
+
+function getDir() {
+  if (typeof __dirname !== 'undefined') {
+    return __dirname;
+  }
+  try {
+    const metaUrl = typeof import.meta !== 'undefined' && import.meta.url ? import.meta.url : null;
+    if (metaUrl && typeof metaUrl === 'string') {
+      const url = new URL(metaUrl);
+      if (url.protocol === 'file:') {
+        return path.dirname(url.pathname);
+      }
+    }
+  } catch (e) {}
+  return process.cwd();
+}
+
+export function getPackageVersion() {
+  try {
+    const dir = getDir();
+    const pkgPath = path.resolve(dir, '../package.json');
+    if (fs.existsSync(pkgPath)) {
+      const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+      if (pkg && typeof pkg.version === 'string' && pkg.version.trim()) {
+        return pkg.version.trim();
+      }
+    }
+  } catch (e) {}
+
+  if (typeof __PACKAGE_VERSION__ !== 'undefined' && __PACKAGE_VERSION__ && __PACKAGE_VERSION__ !== '1.1.41') {
+    return __PACKAGE_VERSION__;
+  }
+
+  return '1.3.14';
+}
+