ysagc-agent 0.3.0 → 0.5.0

package/dist/security.js

@@ -0,0 +1,228 @@
+"use strict";
+/**
+ * Security helpers: dangerous-command detection, sensitive-path detection and
+ * secret masking. These are intentionally conservative — when in doubt the
+ * path/command is treated as unsafe.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MASK = void 0;
+exports.isDangerCommand = isDangerCommand;
+exports.isSensitivePath = isSensitivePath;
+exports.maskSecrets = maskSecrets;
+/**
+ * Rules that flag destructive / privilege-escalating commands. Matching is
+ * case-insensitive and uses word boundaries so ordinary words ("removal",
+ * "formatting") do not trigger a false positive. Rules are cross-platform:
+ * bash, powershell and cmd are all covered.
+ */
+const DANGER_RULES = [
+    // rm -rf / rm -fr / rm -fir etc. (any order of r/f flags)
+    {
+        severity: 'critical',
+        reason: 'recursive/force delete (rm -rf, rm -fr)',
+        re: /\brm\b[^\n]*\s+-[a-z]*r[a-z]*f[a-z]*\b|\brm\b[^\n]*\s+-[a-z]*f[a-z]*r[a-z]*\b/i,
+    },
+    // rm -r on the filesystem root or a system-ish path
+    {
+        severity: 'critical',
+        reason: 'recursive delete targeting a system path (/ , ~, /var, /etc, /dev, /usr, /tmp)',
+        re: /\brm\b[^\n]*\s+-[a-z]*r[a-z]*\s+(?:\\|~\/|\$HOME|\/tmp|\/var|\/etc|\/dev|\/usr|\/boot|\/home)\b/i,
+    },
+    {
+        severity: 'critical',
+        reason: 'privilege escalation (sudo)',
+        re: /\bsudo\b/i,
+    },
+    {
+        severity: 'critical',
+        reason: 'disk format',
+        re: /\bformat\b/i,
+    },
+    // Windows: del /f /q /s (force/quiet/subdirs)
+    {
+        severity: 'critical',
+        reason: 'forced recursive delete (del /f, del /s, del /q)',
+        re: /\bdel\b[^\n]*\s+\/[a-z]*[fsq][a-z]*\b/i,
+    },
+    {
+        severity: 'critical',
+        reason: 'system shutdown',
+        re: /\bshutdown\b/i,
+    },
+    {
+        severity: 'critical',
+        reason: 'system reboot',
+        re: /\breboot\b/i,
+    },
+    {
+        severity: 'danger',
+        reason: 'git hard reset (git reset --hard)',
+        re: /\bgit\b[^\n]*\breset\b[^\n]*--hard\b/i,
+    },
+    {
+        severity: 'danger',
+        reason: 'git clean (git clean -fdx)',
+        re: /\bgit\b[^\n]*\bclean\b[^\n]*-(?:fd?x?|xfd?|dxf|fx)\b/i,
+    },
+    {
+        severity: 'danger',
+        reason: 'find ... -delete',
+        re: /\bfind\b[^\n]*\s-delete\b/i,
+    },
+    {
+        severity: 'critical',
+        reason: 'Remove-Item -Recurse -Force',
+        re: /\bRemove-Item\b[^\n]*-Recurse\b[^\n]*-Force\b/i,
+    },
+    {
+        severity: 'critical',
+        reason: 'move /y to a drive root',
+        re: /\bmove\b[^\n]*\/y\b[^\n]*[a-z]:\\/i,
+    },
+    {
+        severity: 'critical',
+        reason: 'diskpart',
+        re: /\bdiskpart\b/i,
+    },
+    {
+        severity: 'critical',
+        reason: 'registry delete',
+        re: /\breg\b[^\n]*\bdelete\b/i,
+    },
+    {
+        severity: 'danger',
+        reason: 'chmod -R 777 /',
+        re: /\bchmod\b[^\n]*\s+-R\b[^\n]*777\b[^\n]*(?:\\|~|\$HOME|\/etc|\/var|\/dev|\/usr|\/home)\b/i,
+    },
+    {
+        severity: 'danger',
+        reason: 'mkfs (filesystem creation)',
+        re: /\bmkfs\b/i,
+    },
+    {
+        severity: 'critical',
+        reason: 'dd writing to a block device',
+        re: /\bdd\b[^\n]*\bof=\/dev\/\S+/i,
+    },
+    {
+        severity: 'critical',
+        reason: 'redirection to a block device',
+        re: />>?\s*\/dev\/(?:sda|sdb|sd\w|nvme\w*|mmcblk\w*|disk\w*)\b/i,
+    },
+    {
+        severity: 'danger',
+        reason: 'force-kill all processes',
+        re: /\b(?:killall|pkill)\b[^\n]*\s+-9\b|\bkill\b[^\n]*\s+-9\b[^\n]*-?\d+\b/i,
+    },
+    {
+        severity: 'danger',
+        reason: 'fork bomb',
+        re: /:\(\)\s*\{\s*:\|:&\s*\};:/i,
+    },
+    // Truncating the filesystem root or a system file.
+    {
+        severity: 'critical',
+        reason: 'truncate a system path',
+        re: />>?\s*(?:\/etc\/(?:passwd|shadow|hosts)|\/var\/log\b|\/dev\/null\b)/i,
+    },
+];
+/**
+ * Assess whether a shell command is too dangerous to run automatically.
+ * Cross-platform (bash / powershell / cmd). Returns a severity and reason.
+ */
+function isDangerCommand(command) {
+    if (typeof command !== 'string' || command.trim() === '') {
+        return { danger: false, severity: 'none', reason: 'empty command' };
+    }
+    const trimmedTrimmed = command.trim();
+    for (const rule of DANGER_RULES) {
+        if (rule.re.test(trimmedTrimmed)) {
+            return {
+                danger: rule.severity === 'critical' || rule.severity === 'danger',
+                severity: rule.severity,
+                reason: rule.reason,
+            };
+        }
+    }
+    return { danger: false, severity: 'none', reason: 'allowed' };
+}
+/**
+ * High-value / credential paths that are blocked regardless of authorisation
+ * mode. Matched against the lower-cased, slash-normalised path so both POSIX
+ * and Windows spellings are covered.
+ */
+const SENSITIVE_PATTERN = [
+    // System config / credential stores
+    /(^|\/)(etc\/passwd|etc\/shadow|etc\/sudoers|etc\/hosts|etc\/group|etc\/fstab)$/,
+    /(^|\/)(etc\/ssh|etc\/ssl\/private|etc\/ssl\/certs|etc\/pkcs11)/,
+    /(^|\/)(dev\/(sda|sdb|sd[a-z]|nvme[0-9n]+|mmcblk[0-9]+|disk[a-z0-9]+|mem|kmem|initctl|loop[0-9]+|tty))$/,
+    /(^|\/)(proc|sys|boot|run|sbin|bin|usr\/lib|usr\/share|lib|lib64|var\/log|var\/lib|var\/run)\b/,
+    /(^|\/)(system\/library|library\/keychains|library\/preferences|applications)\b/,
+    // Windows system directories
+    /^([a-z]:)?\/(windows|winnt|program files|programdata|users\/(?:default|public)\/appdata)/,
+    /\/windows\/(system32|syswow64|system|security|systemroot|boot)\b/,
+    // Private keys and credential files
+    /(^|\/)(id_rsa|id_dsa|id_ecdsa|id_ed25519)(\.pub)?$/,
+    /(^|\/)\.(ssh|gnupg|aws|azure|kube|docker-npm|config)\b/,
+    /(^|\/)\.env(\.|$)/i,
+    /(^|\/)\.npmrc$/,
+    /(^|\/)(\.netrc|\.pgpass|\.htpasswd|\.htaccess|\.git-credentials|\.boto|\.s3cfg)$/,
+    /(^|\/)(credentials|credentials\.json|secrets?\.json|service-account[^/]*\.json|google-credentials[^/]*\.json|application_default_credentials[^/]*\.json)$/,
+    /(^|\/)(keystore|\.keystore|\.jks|\.p12|\.pfx|\.pem|\.key|cert\.pem|server\.pem)$/,
+    /(^|\/)(\.npmrc|\.yarnrc|\.pypirc|\.gemrc|\.dockerconfigjson)$/,
+    // Files that typically bundle tokens/config keys
+    /(^|\/)(config\.json|settings\.json|secrets\.yml|secrets\.yaml|\.env\.(local|prod|production|dev|development|test))$/,
+];
+/**
+ * Whether a (canonical absolute) path should never be read/written by a tool.
+ * These are blocked no matter what permission mode is in effect.
+ */
+function isSensitivePath(p) {
+    if (typeof p !== 'string' || p === '')
+        return false;
+    const norm = p.replace(/\\/g, '/').toLowerCase();
+    for (const re of SENSITIVE_PATTERN) {
+        if (re.test(norm))
+            return true;
+    }
+    return false;
+}
+/** Emitted value when any secret has been redacted. */
+exports.MASK = '***';
+/**
+ * Redact secrets from a string: provider keys, bearer tokens, JWTs, private
+ * keys, and `key=value` / `key: value` pairs for obvious secret names. Used
+ * before logging or returning tool output so internal keys never leak.
+ */
+function maskSecrets(text) {
+    if (typeof text !== 'string' || text === '')
+        return text;
+    let out = text;
+    // Named secret pairs: password=..., token=..., api_key=..., authorization: ...
+    out = out.replace(/(password|passwd|secret|token|api[_-]?key|access[_-]?key|auth(?:orization)?|session|refresh[_-]?token|private[_-]?key|cookie|client[_-]?secret)\s*(?:[:=]\s*|["']?\s+)(["']?)([^\s,;'"&]+)\2/gi, (_m, _key, _q, value) => {
+        // Never redact a placeholder already present.
+        if (value === exports.MASK)
+            return _m;
+        return `${_q}${exports.MASK}${_q}`;
+    });
+    // Bearer / Basic auth headers.
+    out = out.replace(/\b(Bearer|Basic)\s+[A-Za-z0-9+/=_-]{8,}/gi, `$1 ${exports.MASK}`);
+    // OpenAI / Anthropic style sk- keys.
+    out = out.replace(/\bsk-[A-Za-z0-9_-]{16,}\b/g, `sk-${exports.MASK}`);
+    // Stripe live/test keys.
+    out = out.replace(/\bsk_(?:live|test)_[A-Za-z0-9]{16,}\b/g, `sk_${exports.MASK}`);
+    // GitHub tokens.
+    out = out.replace(/\bgh[pousr]_[A-Za-z0-9]{16,}\b/g, `gh${exports.MASK}`.replace('***', exports.MASK));
+    // Slack tokens.
+    out = out.replace(/\bxox[baprs]-[A-Za-z0-9-]{10,}\b/g, `xox${exports.MASK}`.replace('***', exports.MASK));
+    // Google API keys.
+    out = out.replace(/\bAIza[0-9A-Za-z_-]{30,}\b/g, `AIza${exports.MASK}`);
+    // AWS access key ID.
+    out = out.replace(/\b(AKIA|ASIA)[0-9A-Z]{16}\b/g, `$1${exports.MASK}`);
+    // JWT.
+    out = out.replace(/\beyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\b/g, `eyJ${exports.MASK}`);
+    // PEM / OpenSSH private-key blocks.
+    out = out.replace(/-----BEGIN ([A-Z ]*)?PRIVATE KEY-----[\s\S]*?-----END ([A-Z ]*)?PRIVATE KEY-----/g, '-----BEGIN PRIVATE KEY-----\n' + exports.MASK + '\n-----END PRIVATE KEY-----');
+    return out;
+}
+//# sourceMappingURL=security.js.map

package/dist/security.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"security.js","sourceRoot":"","sources":["../src/security.ts"],"names":[],"mappings":"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"}

package/dist/skills.d.ts

@@ -0,0 +1,16 @@
+/** List available skill names in `<root>/.dsh/skills`. */
+export declare function listSkills(root: string): string[];
+/** Return the content of a single skill, or undefined when it does not exist
+ * (or the name is unsafe / the read fails). */
+export declare function loadSkill(root: string, name: string): string | undefined;
+export interface SkillRecord {
+    loaded: boolean;
+    name?: string;
+    content?: string;
+    available: string[];
+    note?: string;
+}
+/** Load a skill by name into a structured record, or return a "not found" /
+ * "no skills configured" record. */
+export declare function loadSkillRecord(root: string, name?: string): SkillRecord;
+//# sourceMappingURL=skills.d.ts.map

package/dist/skills.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skills.d.ts","sourceRoot":"","sources":["../src/skills.ts"],"names":[],"mappings":"AAoBA,0DAA0D;AAC1D,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAWjD;AAED;+CAC+C;AAC/C,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAWxE;AAED,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,OAAO,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;oCACoC;AACpC,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,WAAW,CAkBxE"}

package/dist/skills.js

@@ -0,0 +1,105 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.listSkills = listSkills;
+exports.loadSkill = loadSkill;
+exports.loadSkillRecord = loadSkillRecord;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+/**
+ * A lightweight, file-backed skills registry. Skills are Markdown files that
+ * live under `<workspace-root>/.dsh/skills/<name>.md`. The registry never
+ * throws: when the directory is absent or a skill is missing it simply reports
+ * "none found" so the agent stays non-fatal.
+ */
+const SKILLS_SUBDIR = path.join('.dsh', 'skills');
+function skillsDir(root) {
+    return path.join(root, SKILLS_SUBDIR);
+}
+function isValidName(name) {
+    return typeof name === 'string' && /^[A-Za-z0-9._-]+$/.test(name);
+}
+/** List available skill names in `<root>/.dsh/skills`. */
+function listSkills(root) {
+    const dir = skillsDir(root);
+    try {
+        const names = fs.readdirSync(dir);
+        return names
+            .filter((n) => n.endsWith('.md'))
+            .map((n) => n.slice(0, -3))
+            .sort();
+    }
+    catch {
+        return [];
+    }
+}
+/** Return the content of a single skill, or undefined when it does not exist
+ * (or the name is unsafe / the read fails). */
+function loadSkill(root, name) {
+    if (!isValidName(name))
+        return undefined;
+    const file = path.join(skillsDir(root), `${name}.md`);
+    try {
+        // Guard against reading a directory.
+        const stat = fs.statSync(file);
+        if (!stat.isFile())
+            return undefined;
+        return fs.readFileSync(file, 'utf8');
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Load a skill by name into a structured record, or return a "not found" /
+ * "no skills configured" record. */
+function loadSkillRecord(root, name) {
+    const available = listSkills(root);
+    if (!name || name.trim() === '') {
+        return {
+            loaded: false,
+            available,
+            note: 'No skill name supplied.',
+        };
+    }
+    const content = loadSkill(root, name);
+    if (content === undefined) {
+        const note = available.length === 0
+            ? `No skills are configured in ${skillsDir(root)}.`
+            : `Skill "${name}" not found. Available: ${available.join(', ')}.`;
+        return { loaded: false, name, available, note };
+    }
+    return { loaded: true, name, content, available };
+}
+//# sourceMappingURL=skills.js.map

package/dist/skills.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"skills.js","sourceRoot":"","sources":["../src/skills.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAqBA,gCAWC;AAID,8BAWC;AAYD,0CAkBC;AA7ED,4CAA8B;AAC9B,gDAAkC;AAElC;;;;;GAKG;AAEH,MAAM,aAAa,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;AAElD,SAAS,SAAS,CAAC,IAAY;IAC7B,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,aAAa,CAAC,CAAC;AACxC,CAAC;AAED,SAAS,WAAW,CAAC,IAAY;IAC/B,OAAO,OAAO,IAAI,KAAK,QAAQ,IAAI,mBAAmB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACpE,CAAC;AAED,0DAA0D;AAC1D,SAAgB,UAAU,CAAC,IAAY;IACrC,MAAM,GAAG,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC;IAC5B,IAAI,CAAC;QACH,MAAM,KAAK,GAAG,EAAE,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;QAClC,OAAO,KAAK;aACT,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;aAChC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;aAC1B,IAAI,EAAE,CAAC;IACZ,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC;AAED;+CAC+C;AAC/C,SAAgB,SAAS,CAAC,IAAY,EAAE,IAAY;IAClD,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC;QAAE,OAAO,SAAS,CAAC;IACzC,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,GAAG,IAAI,KAAK,CAAC,CAAC;IACtD,IAAI,CAAC;QACH,qCAAqC;QACrC,MAAM,IAAI,GAAG,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;QAC/B,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE;YAAE,OAAO,SAAS,CAAC;QACrC,OAAO,EAAE,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IACvC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC;AAUD;oCACoC;AACpC,SAAgB,eAAe,CAAC,IAAY,EAAE,IAAa;IACzD,MAAM,SAAS,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC;IACnC,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;QAChC,OAAO;YACL,MAAM,EAAE,KAAK;YACb,SAAS;YACT,IAAI,EAAE,yBAAyB;SAChC,CAAC;IACJ,CAAC;IACD,MAAM,OAAO,GAAG,SAAS,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IACtC,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;QAC1B,MAAM,IAAI,GACR,SAAS,CAAC,MAAM,KAAK,CAAC;YACpB,CAAC,CAAC,+BAA+B,SAAS,CAAC,IAAI,CAAC,GAAG;YACnD,CAAC,CAAC,UAAU,IAAI,2BAA2B,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC;QACvE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;IAClD,CAAC;IACD,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,SAAS,EAAE,CAAC;AACpD,CAAC"}

package/dist/tokens.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Lightweight token accounting. This agent never calls an LLM directly, so the
+ * platform supplies exact usage when it can; otherwise we fall back to a cheap
+ * characters-per-token estimate so every turn still reports an approximate
+ * request/response token count.
+ */
+/**
+ * Estimate the number of tokens in a piece of plain text. A very cheap,
+ * deterministic approximation: `ceil(chars / 4)` with a floor of 1 for
+ * non-empty text. Not an exact BPE count, but monotonic and stable enough for
+ * reporting purposes.
+ */
+export declare function countTextTokens(text: string): number;
+/** Serialise an arbitrary value (deep) and count its estimated tokens. */
+export declare function estimateTokens(value: unknown): number;
+export interface TokenUsage {
+    /** Approximate tokens consumed by the request / tool arguments. */
+    inputTokens: number;
+    /** Approximate tokens emitted by the response / tool result. */
+    outputTokens: number;
+    /** inputTokens + outputTokens. */
+    totalTokens: number;
+}
+/** Build a token usage report from a request payload and its response. */
+export declare function computeUsage(input: unknown, output: unknown): TokenUsage;
+//# sourceMappingURL=tokens.d.ts.map

package/dist/tokens.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tokens.d.ts","sourceRoot":"","sources":["../src/tokens.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAMpD;AAED,0EAA0E;AAC1E,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAUrD;AAED,MAAM,WAAW,UAAU;IACzB,mEAAmE;IACnE,WAAW,EAAE,MAAM,CAAC;IACpB,gEAAgE;IAChE,YAAY,EAAE,MAAM,CAAC;IACrB,kCAAkC;IAClC,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,0EAA0E;AAC1E,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,GAAG,UAAU,CAIxE"}

package/dist/tokens.js

@@ -0,0 +1,50 @@
+"use strict";
+/**
+ * Lightweight token accounting. This agent never calls an LLM directly, so the
+ * platform supplies exact usage when it can; otherwise we fall back to a cheap
+ * characters-per-token estimate so every turn still reports an approximate
+ * request/response token count.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.countTextTokens = countTextTokens;
+exports.estimateTokens = estimateTokens;
+exports.computeUsage = computeUsage;
+/** Rough characters-per-token heuristic (English-ish text). */
+const CHARS_PER_TOKEN = 4;
+/**
+ * Estimate the number of tokens in a piece of plain text. A very cheap,
+ * deterministic approximation: `ceil(chars / 4)` with a floor of 1 for
+ * non-empty text. Not an exact BPE count, but monotonic and stable enough for
+ * reporting purposes.
+ */
+function countTextTokens(text) {
+    if (typeof text !== 'string' || text === '')
+        return 0;
+    // Strip whitespace runs and count remaining characters in 4-char blocks.
+    const squeezed = text.replace(/\s+/g, ' ').trim();
+    if (squeezed === '')
+        return 0;
+    return Math.max(1, Math.ceil(squeezed.length / CHARS_PER_TOKEN));
+}
+/** Serialise an arbitrary value (deep) and count its estimated tokens. */
+function estimateTokens(value) {
+    if (value === undefined || value === null)
+        return 0;
+    if (typeof value === 'string')
+        return countTextTokens(value);
+    let text;
+    try {
+        text = JSON.stringify(value);
+    }
+    catch {
+        text = String(value);
+    }
+    return countTextTokens(text ?? '');
+}
+/** Build a token usage report from a request payload and its response. */
+function computeUsage(input, output) {
+    const inputTokens = estimateTokens(input);
+    const outputTokens = estimateTokens(output);
+    return { inputTokens, outputTokens, totalTokens: inputTokens + outputTokens };
+}
+//# sourceMappingURL=tokens.js.map

package/dist/tokens.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tokens.js","sourceRoot":"","sources":["../src/tokens.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;AAWH,0CAMC;AAGD,wCAUC;AAYD,oCAIC;AA5CD,+DAA+D;AAC/D,MAAM,eAAe,GAAG,CAAC,CAAC;AAE1B;;;;;GAKG;AACH,SAAgB,eAAe,CAAC,IAAY;IAC1C,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,EAAE;QAAE,OAAO,CAAC,CAAC;IACtD,yEAAyE;IACzE,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;IAClD,IAAI,QAAQ,KAAK,EAAE;QAAE,OAAO,CAAC,CAAC;IAC9B,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,GAAG,eAAe,CAAC,CAAC,CAAC;AACnE,CAAC;AAED,0EAA0E;AAC1E,SAAgB,cAAc,CAAC,KAAc;IAC3C,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,CAAC,CAAC;IACpD,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,eAAe,CAAC,KAAK,CAAC,CAAC;IAC7D,IAAI,IAAY,CAAC;IACjB,IAAI,CAAC;QACH,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IAC/B,CAAC;IAAC,MAAM,CAAC;QACP,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;IACvB,CAAC;IACD,OAAO,eAAe,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC;AACrC,CAAC;AAWD,0EAA0E;AAC1E,SAAgB,YAAY,CAAC,KAAc,EAAE,MAAe;IAC1D,MAAM,WAAW,GAAG,cAAc,CAAC,KAAK,CAAC,CAAC;IAC1C,MAAM,YAAY,GAAG,cAAc,CAAC,MAAM,CAAC,CAAC;IAC5C,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,WAAW,EAAE,WAAW,GAAG,YAAY,EAAE,CAAC;AAChF,CAAC"}

package/dist/tools.d.ts

@@ -0,0 +1,69 @@
+import type { PermissionMode, PermissionPreset } from './config';
+import type { Logger } from './logger';
+/** Thrown when a tool invocation is invalid or unsafe. */
+export declare class ToolError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+export interface ToolContext {
+    /** Canonical authorised root; all file operations stay inside it. */
+    root: string;
+    mode: PermissionMode;
+    /** Sandbox-mode × approval preset for the guarded gate. */
+    permissionPreset?: PermissionPreset;
+    webEnabled: boolean;
+    timeoutMs: number;
+    maxBytes: number;
+    logger: Logger;
+}
+export interface ToolOutcome {
+    ok: boolean;
+    result?: unknown;
+    error?: string;
+    /** Set when the guarded gate requires platform approval before running. */
+    needsApproval?: boolean;
+}
+export interface ToolResult extends ToolOutcome {
+    durationMs: number;
+    /** Set when the result came from the idempotency cache. */
+    cached?: boolean;
+}
+export type ToolExecutor = (ctx: ToolContext, args: Record<string, unknown>, signal?: AbortSignal) => Promise<ToolOutcome>;
+export interface PreCheckOutcome {
+    ok: boolean;
+    error?: string;
+    /** Set when a workspace-write gate would prompt the platform for approval. */
+    needsApproval?: boolean;
+    /** Human-readable reason for the decision. */
+    reason?: string;
+}
+export interface PostCheckOutcome {
+    ok: boolean;
+    error?: string;
+    reason?: string;
+}
+/**
+ * The guarded pre-execution hook. Runs before every tool:
+ *  1. enforces the permission preset (read-only blocks writes/commands);
+ *  2. flags dangerous commands (workspace-write asks for approval, most
+ *     permissive mode only blocks critical commands, read-only blocks all);
+ *  3. canonicalises and validates every path argument (inside-root + sensitive
+ *     path check).
+ * Returns `{ ok: true }` when execution may proceed, otherwise a structured
+ * block with an error and optional `needsApproval`.
+ */
+export declare function preExecute(ctx: ToolContext, tool: string, args: Record<string, unknown>): PreCheckOutcome;
+/**
+ * The guarded post-execution hook. Runs after every tool: masks secrets in the
+ * result and records the reason the invocation ended up here.
+ */
+export declare function postExecute(_ctx: ToolContext, tool: string, result: ToolResult): PostCheckOutcome;
+export interface ToolRegistry {
+    readonly ctx: ToolContext;
+    readonly tools: readonly string[];
+    has(name: string): boolean;
+    dispatch(name: string, args: Record<string, unknown>, signal?: AbortSignal): Promise<ToolResult>;
+}
+/** Build a tool registry bound to a single execution context. */
+export declare function createToolRegistry(ctx: ToolContext): ToolRegistry;
+//# sourceMappingURL=tools.d.ts.map

package/dist/tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AACjE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAEvC,0DAA0D;AAC1D,qBAAa,SAAU,SAAQ,KAAK;IAClC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBACV,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;CAK1C;AAED,MAAM,WAAW,WAAW;IAC1B,qEAAqE;IACrE,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,cAAc,CAAC;IACrB,2DAA2D;IAC3D,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;IACpC,UAAU,EAAE,OAAO,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,2EAA2E;IAC3E,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED,MAAM,WAAW,UAAW,SAAQ,WAAW;IAC7C,UAAU,EAAE,MAAM,CAAC;IACnB,2DAA2D;IAC3D,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,MAAM,YAAY,GAAG,CACzB,GAAG,EAAE,WAAW,EAChB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,MAAM,CAAC,EAAE,WAAW,KACjB,OAAO,CAAC,WAAW,CAAC,CAAC;AAqH1B,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,OAAO,CAAC;IACZ,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,8EAA8E;IAC9E,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,8CAA8C;IAC9C,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,OAAO,CAAC;IACZ,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAoDD;;;;;;;;;GASG;AACH,wBAAgB,UAAU,CACxB,GAAG,EAAE,WAAW,EAChB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC5B,eAAe,CA6DjB;AAgBD;;;GAGG;AACH,wBAAgB,WAAW,CACzB,IAAI,EAAE,WAAW,EACjB,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,UAAU,GACjB,gBAAgB,CAWlB;AAmWD,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,GAAG,EAAE,WAAW,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;CAClG;AAED,iEAAiE;AACjE,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,WAAW,GAAG,YAAY,CA6DjE"}