@ory/argus 0.1.0

package/dist/skills.js

@@ -0,0 +1,264 @@
+"use strict";
+/**
+ * Canonical Ory agent skills and commands.
+ *
+ * The skill playbooks (auth-setup, login-flow, social-login, local-dev) and the
+ * local-stack commands (local-up, local-down) live once, as token-bearing
+ * templates under `packages/core/assets/`. Every harness plugin renders them
+ * through {@link renderOrySkills} / {@link renderOryCommands}, substituting the
+ * harness's CLI binary, package name, and the way it references sibling skills
+ * and commands. Plugins then write the rendered docs into whatever location
+ * their harness discovers skills/commands from (a marketplace plugin dir, an
+ * extension bundle, `~/.codex/skills`, `.opencode/skills`, …).
+ *
+ * This keeps the ~1200 lines of guidance in one place — there is no per-harness
+ * copy to drift.
+ */
+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.ORY_COMMAND_SLUGS = exports.ORY_COMMAND_SKILL_NAMES = exports.ORY_SKILL_NAMES = void 0;
+exports.renderOrySkills = renderOrySkills;
+exports.renderOryCommands = renderOryCommands;
+exports.toSkillMarkdown = toSkillMarkdown;
+exports.commandToSkill = commandToSkill;
+exports.commandToToml = commandToToml;
+exports.commandToFrontmatterMarkdown = commandToFrontmatterMarkdown;
+exports.commandToPlainMarkdown = commandToPlainMarkdown;
+exports.writeSkillTree = writeSkillTree;
+exports.removeSkillDirs = removeSkillDirs;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const SKILL_SOURCES = [
+    { id: "auth-setup", name: "ory-auth-setup", file: "skills/auth-setup/SKILL.md" },
+    { id: "login-flow", name: "ory-login-flow", file: "skills/login-flow/SKILL.md" },
+    { id: "social-login", name: "ory-social-login", file: "skills/social-login/SKILL.md" },
+    { id: "local-dev", name: "ory-local-dev", file: "skills/local-dev/SKILL.md" },
+];
+const COMMAND_SOURCES = [
+    {
+        id: "local-up",
+        name: "ory-local-up",
+        slug: "local-up",
+        description: "Start the local Ory dev stack (Kratos, Keto, Hydra, gateway) in Docker and seed test data.",
+        file: "commands/local-up.md",
+    },
+    {
+        id: "local-down",
+        name: "ory-local-down",
+        slug: "local-down",
+        description: "Stop the local Ory dev stack, preserving data volumes.",
+        file: "commands/local-down.md",
+    },
+];
+/** Names of the skills materialized by the plugins (for uninstall cleanup). */
+exports.ORY_SKILL_NAMES = SKILL_SOURCES.map((s) => s.name);
+/** Skill names of the local-stack commands when rendered as skills. */
+exports.ORY_COMMAND_SKILL_NAMES = COMMAND_SOURCES.map((c) => c.name);
+/** File stems of the local-stack commands when rendered as commands. */
+exports.ORY_COMMAND_SLUGS = COMMAND_SOURCES.map((c) => c.slug);
+/** Backtick-wrap an inline code reference. */
+function code(value) {
+    return "`" + value + "`";
+}
+/**
+ * Build the token substitution map for a harness. The reference style differs:
+ *
+ * - Claude Code addresses sibling skills as `/project:<name>` and the commands
+ *   as `/ory:local-up`.
+ * - Gemini CLI and OpenCode expose the commands as real slash commands
+ *   (`/ory:local-up`) but model-invoke skills by name.
+ * - Codex and OpenClaw render the commands as user-invocable skills, so both
+ *   skills and commands are referenced by their bare skill name.
+ */
+function buildProfile(harness, opts) {
+    const skillRef = (name) => harness === "claude-code" ? code(`/project:${name}`) : code(name);
+    let localUp;
+    let localDown;
+    switch (harness) {
+        case "claude-code":
+        case "gemini-cli":
+        case "opencode":
+            localUp = code("/ory:local-up");
+            localDown = code("/ory:local-down");
+            break;
+        case "codex":
+        case "openclaw":
+        default:
+            localUp = code("ory-local-up");
+            localDown = code("ory-local-down");
+            break;
+    }
+    return {
+        binName: opts.binName,
+        packageName: opts.packageName,
+        tokens: {
+            "{{BIN}}": opts.binName,
+            "{{PKG}}": opts.packageName,
+            "{{REF_AUTH_SETUP}}": skillRef("ory-auth-setup"),
+            "{{REF_LOGIN_FLOW}}": skillRef("ory-login-flow"),
+            "{{REF_SOCIAL_LOGIN}}": skillRef("ory-social-login"),
+            "{{REF_LOCAL_DEV}}": skillRef("ory-local-dev"),
+            "{{REF_LOCAL_UP}}": localUp,
+            "{{REF_LOCAL_DOWN}}": localDown,
+        },
+    };
+}
+// ─── Template loading + substitution ────────────────────────────────
+/**
+ * Resolve the assets root. The compiled module lives at `dist/skills.js` and
+ * tests run it from `src/skills.ts`; in both cases the `assets/` tree sits one
+ * level up at the package root. Published consumers get `assets/` via the
+ * package `files` allowlist.
+ */
+function getAssetsDir() {
+    const candidate = path.join(__dirname, "..", "assets");
+    if (fs.existsSync(path.join(candidate, "skills")))
+        return candidate;
+    throw new Error(`Ory skill assets not found at ${candidate}. The @ory/argus package must ship its 'assets' directory.`);
+}
+function applyTokens(template, tokens) {
+    let out = template;
+    for (const [token, value] of Object.entries(tokens)) {
+        out = out.split(token).join(value);
+    }
+    return out;
+}
+/** Parse the minimal `name` / `description` frontmatter from a SKILL.md. */
+function parseFrontmatter(markdown) {
+    const match = /^---\n([\s\S]*?)\n---\n?/.exec(markdown);
+    if (!match) {
+        return { name: "", description: "", body: markdown };
+    }
+    const block = match[1];
+    const body = markdown.slice(match[0].length).replace(/^\n+/, "");
+    const read = (key) => {
+        const m = new RegExp(`^${key}:\\s*(.*)$`, "m").exec(block);
+        return m ? m[1].trim() : "";
+    };
+    return { name: read("name"), description: read("description"), body };
+}
+// ─── Public render API ──────────────────────────────────────────────
+/**
+ * Render the four guide skills for a harness as `SKILL.md` documents.
+ */
+function renderOrySkills(harness, opts) {
+    const profile = buildProfile(harness, opts);
+    const assets = getAssetsDir();
+    return SKILL_SOURCES.map((src) => {
+        const template = fs.readFileSync(path.join(assets, src.file), "utf-8");
+        const markdown = applyTokens(template, profile.tokens);
+        const { name, description, body } = parseFrontmatter(markdown);
+        return {
+            id: src.id,
+            name: name || src.name,
+            description,
+            body,
+            markdown,
+        };
+    });
+}
+/**
+ * Render the two local-stack commands for a harness. The `body` is the rendered
+ * markdown; callers format it into the harness's command shape (plain markdown,
+ * TOML, frontmatter markdown) or wrap it as a skill via {@link commandToSkill}.
+ */
+function renderOryCommands(harness, opts) {
+    const profile = buildProfile(harness, opts);
+    const assets = getAssetsDir();
+    return COMMAND_SOURCES.map((src) => {
+        const template = fs.readFileSync(path.join(assets, src.file), "utf-8");
+        return {
+            id: src.id,
+            name: src.name,
+            slug: src.slug,
+            description: src.description,
+            body: applyTokens(template, profile.tokens),
+        };
+    });
+}
+// ─── Format helpers ─────────────────────────────────────────────────
+/** Compose a `SKILL.md` from its parts. */
+function toSkillMarkdown(name, description, body) {
+    const trimmedBody = body.replace(/^\n+/, "").replace(/\s+$/, "");
+    return `---\nname: ${name}\ndescription: ${description}\n---\n\n${trimmedBody}\n`;
+}
+/** Wrap a rendered command as a user-invocable skill (Codex, OpenClaw). */
+function commandToSkill(cmd) {
+    const markdown = toSkillMarkdown(cmd.name, cmd.description, cmd.body);
+    const { body } = parseFrontmatter(markdown);
+    return { id: cmd.id, name: cmd.name, description: cmd.description, body, markdown };
+}
+function tomlBasicString(value) {
+    return '"' + value.replace(/\\/g, "\\\\").replace(/"/g, '\\"') + '"';
+}
+/** Render a command as a Gemini CLI TOML command definition. */
+function commandToToml(cmd) {
+    const body = cmd.body.replace(/\s+$/, "");
+    // TOML multiline literal strings ('''…''') don't process escapes, which is
+    // safe for markdown bodies (they contain backticks and quotes, never ''').
+    return (`# Generated from @ory/argus command templates — do not edit by hand.\n` +
+        `description = ${tomlBasicString(cmd.description)}\n` +
+        `prompt = '''\n${body}\n'''\n`);
+}
+/** Render a command as an OpenCode markdown command (frontmatter + body). */
+function commandToFrontmatterMarkdown(cmd) {
+    const body = cmd.body.replace(/^\n+/, "").replace(/\s+$/, "");
+    return `---\ndescription: ${cmd.description}\n---\n\n${body}\n`;
+}
+/** Render a command as a plain markdown command file (Claude Code). */
+function commandToPlainMarkdown(cmd) {
+    return cmd.body.replace(/\s+$/, "") + "\n";
+}
+// ─── Writers ────────────────────────────────────────────────────────
+/**
+ * Write each skill into `<skillsDir>/<name>/SKILL.md`. Overwrites existing
+ * files; creates directories as needed.
+ */
+function writeSkillTree(skillsDir, skills) {
+    for (const skill of skills) {
+        const dir = path.join(skillsDir, skill.name);
+        fs.mkdirSync(dir, { recursive: true });
+        fs.writeFileSync(path.join(dir, "SKILL.md"), skill.markdown);
+    }
+}
+/** Remove the named skill directories from `skillsDir` (best-effort). */
+function removeSkillDirs(skillsDir, names) {
+    for (const name of names) {
+        const dir = path.join(skillsDir, name);
+        if (fs.existsSync(dir)) {
+            fs.rmSync(dir, { recursive: true, force: true });
+        }
+    }
+}

package/dist/subject.d.ts

@@ -0,0 +1,43 @@
+/**
+ * User-subject resolution for permission checks.
+ *
+ * Permission checks need a subject reference that matches the form
+ * stored in Keto. Two shapes are supported:
+ *
+ *   - **SubjectSet** — `<namespace>:<object>` (e.g. `User:<UUID>`). This
+ *     is the form the Console's *Add relationship* dialog writes, so
+ *     dev/demo flows that grant tuples through the UI use it.
+ *
+ *   - **Direct SubjectID** — opaque string (e.g. `user:<UUID>` or
+ *     `session:<id>`). Backward-compatible default when no subject
+ *     namespace is configured.
+ *
+ * The selection is driven by `ORY_USER_SUBJECT_NAMESPACE`: when set, the
+ * resolver builds a SubjectSet using that namespace; when unset, it
+ * falls back to the direct SubjectID chain.
+ */
+import type { OryAgentClient } from "./client.js";
+export type UserSubjectRef = {
+    subjectId: string;
+} | {
+    subjectSet: {
+        namespace: string;
+        object: string;
+        relation: string;
+    };
+};
+/**
+ * Resolve the user subject for permission checks. Prefers the auth-gate's
+ * `userPrincipal.subject`, falls back to `ORY_USER_SUBJECT_ID`, then the
+ * legacy `ORY_AGENT_SUBJECT_ID`, then the caller-supplied `fallback`
+ * (typically `session:<id>`).
+ *
+ * Returns a SubjectSet when `ORY_USER_SUBJECT_NAMESPACE` is set and a
+ * concrete subject is available; otherwise a direct SubjectID.
+ */
+export declare function resolveUserSubject(client: OryAgentClient, fallback?: string): UserSubjectRef;
+/**
+ * Printable label for a `UserSubjectRef`. Used in denial messages and
+ * span attributes. SubjectSets render as `<namespace>:<object>`.
+ */
+export declare function subjectLabel(ref: UserSubjectRef): string;

package/dist/subject.js

@@ -0,0 +1,55 @@
+"use strict";
+/**
+ * User-subject resolution for permission checks.
+ *
+ * Permission checks need a subject reference that matches the form
+ * stored in Keto. Two shapes are supported:
+ *
+ *   - **SubjectSet** — `<namespace>:<object>` (e.g. `User:<UUID>`). This
+ *     is the form the Console's *Add relationship* dialog writes, so
+ *     dev/demo flows that grant tuples through the UI use it.
+ *
+ *   - **Direct SubjectID** — opaque string (e.g. `user:<UUID>` or
+ *     `session:<id>`). Backward-compatible default when no subject
+ *     namespace is configured.
+ *
+ * The selection is driven by `ORY_USER_SUBJECT_NAMESPACE`: when set, the
+ * resolver builds a SubjectSet using that namespace; when unset, it
+ * falls back to the direct SubjectID chain.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveUserSubject = resolveUserSubject;
+exports.subjectLabel = subjectLabel;
+/**
+ * Resolve the user subject for permission checks. Prefers the auth-gate's
+ * `userPrincipal.subject`, falls back to `ORY_USER_SUBJECT_ID`, then the
+ * legacy `ORY_AGENT_SUBJECT_ID`, then the caller-supplied `fallback`
+ * (typically `session:<id>`).
+ *
+ * Returns a SubjectSet when `ORY_USER_SUBJECT_NAMESPACE` is set and a
+ * concrete subject is available; otherwise a direct SubjectID.
+ */
+function resolveUserSubject(client, fallback) {
+    const subject = client.userPrincipal.subject
+        ?? process.env.ORY_USER_SUBJECT_ID
+        ?? process.env.ORY_AGENT_SUBJECT_ID
+        ?? fallback;
+    const ns = process.env.ORY_USER_SUBJECT_NAMESPACE;
+    if (subject && ns) {
+        return {
+            subjectSet: { namespace: ns, object: subject, relation: "" },
+        };
+    }
+    if (subject)
+        return { subjectId: subject };
+    return { subjectId: "agent:unknown" };
+}
+/**
+ * Printable label for a `UserSubjectRef`. Used in denial messages and
+ * span attributes. SubjectSets render as `<namespace>:<object>`.
+ */
+function subjectLabel(ref) {
+    return "subjectSet" in ref
+        ? `${ref.subjectSet.namespace}:${ref.subjectSet.object}`
+        : ref.subjectId;
+}

package/dist/tool-metadata.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Privacy-preserving summarizers for tool input/output.
+ *
+ * Plugins must NEVER record raw tool content (commands, file bodies,
+ * URLs with query strings, prompts) directly into trace attributes.
+ * These helpers emit only:
+ *   - byte size (proxy for "how much data")
+ *   - sha256-truncated content hash (for dedup / "we've seen this before")
+ *   - a small set of safe per-tool fields (exit code, file path, URL host)
+ *
+ * Anything that could reflect content goes through here so the redaction
+ * policy lives in one place.
+ */
+export interface ToolInputSummary {
+    inputBytes?: number;
+    inputHash?: string;
+    /** Bash/shell — not the command itself. */
+    bashCommandBytes?: number;
+    bashCommandHash?: string;
+    /** File ops — path is metadata, file *contents* are not captured. */
+    filePath?: string;
+    /** Network ops — host only, never path or query string. */
+    urlHost?: string;
+}
+export interface ToolOutputSummary {
+    outputBytes?: number;
+    outputHash?: string;
+    /** Bash/shell exit code. */
+    bashExitCode?: number;
+    bashStdoutBytes?: number;
+    bashStderrBytes?: number;
+}
+/**
+ * Summarize a tool input value. `input` is whatever the harness passed —
+ * usually an object like `{ command: "..." }` or `{ file_path: "..." }`.
+ */
+export declare function summarizeToolInput(toolName: string, input: unknown): ToolInputSummary;
+/**
+ * Summarize a tool output/response value.
+ */
+export declare function summarizeToolOutput(toolName: string, output: unknown): ToolOutputSummary;

package/dist/tool-metadata.js

@@ -0,0 +1,127 @@
+"use strict";
+/**
+ * Privacy-preserving summarizers for tool input/output.
+ *
+ * Plugins must NEVER record raw tool content (commands, file bodies,
+ * URLs with query strings, prompts) directly into trace attributes.
+ * These helpers emit only:
+ *   - byte size (proxy for "how much data")
+ *   - sha256-truncated content hash (for dedup / "we've seen this before")
+ *   - a small set of safe per-tool fields (exit code, file path, URL host)
+ *
+ * Anything that could reflect content goes through here so the redaction
+ * policy lives in one place.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.summarizeToolInput = summarizeToolInput;
+exports.summarizeToolOutput = summarizeToolOutput;
+const node_crypto_1 = require("node:crypto");
+const HASH_PREFIX_LEN = 16;
+/**
+ * Summarize a tool input value. `input` is whatever the harness passed —
+ * usually an object like `{ command: "..." }` or `{ file_path: "..." }`.
+ */
+function summarizeToolInput(toolName, input) {
+    if (input === undefined || input === null)
+        return {};
+    const result = {};
+    const serialized = stableSerialize(input);
+    if (serialized !== undefined) {
+        result.inputBytes = Buffer.byteLength(serialized, "utf8");
+        result.inputHash = sha256Prefix(serialized);
+    }
+    if (typeof input === "object") {
+        const obj = input;
+        // Bash / shell tools: capture command size + hash, never the command itself.
+        const command = pickString(obj, ["command", "cmd"]);
+        if (command !== undefined && isBashLikeTool(toolName)) {
+            result.bashCommandBytes = Buffer.byteLength(command, "utf8");
+            result.bashCommandHash = sha256Prefix(command);
+        }
+        // File ops: path is metadata. We do NOT capture file content/body fields
+        // (e.g. `content`, `new_string`, `text`, `body`).
+        const filePath = pickString(obj, ["file_path", "filePath", "path"]);
+        if (filePath !== undefined) {
+            result.filePath = filePath;
+        }
+        // Network/fetch tools: extract host only, drop path + query string.
+        const url = pickString(obj, ["url", "URL", "endpoint"]);
+        if (url !== undefined) {
+            const host = extractHost(url);
+            if (host)
+                result.urlHost = host;
+        }
+    }
+    return result;
+}
+/**
+ * Summarize a tool output/response value.
+ */
+function summarizeToolOutput(toolName, output) {
+    if (output === undefined || output === null)
+        return {};
+    const result = {};
+    const serialized = stableSerialize(output);
+    if (serialized !== undefined) {
+        result.outputBytes = Buffer.byteLength(serialized, "utf8");
+        result.outputHash = sha256Prefix(serialized);
+    }
+    if (typeof output === "object") {
+        const obj = output;
+        if (isBashLikeTool(toolName)) {
+            const exit = obj.exitCode ?? obj.exit_code ?? obj.exit;
+            if (typeof exit === "number")
+                result.bashExitCode = exit;
+            const stdout = pickString(obj, ["stdout"]);
+            if (stdout !== undefined) {
+                result.bashStdoutBytes = Buffer.byteLength(stdout, "utf8");
+            }
+            const stderr = pickString(obj, ["stderr"]);
+            if (stderr !== undefined) {
+                result.bashStderrBytes = Buffer.byteLength(stderr, "utf8");
+            }
+        }
+    }
+    return result;
+}
+// ─── Helpers ──────────────────────────────────────────────────────
+function stableSerialize(v) {
+    if (typeof v === "string")
+        return v;
+    try {
+        return JSON.stringify(v);
+    }
+    catch {
+        return undefined;
+    }
+}
+function sha256Prefix(s) {
+    return (0, node_crypto_1.createHash)("sha256").update(s).digest("hex").slice(0, HASH_PREFIX_LEN);
+}
+function pickString(obj, keys) {
+    for (const k of keys) {
+        const v = obj[k];
+        if (typeof v === "string" && v.length > 0)
+            return v;
+    }
+    return undefined;
+}
+function isBashLikeTool(toolName) {
+    const lower = toolName.toLowerCase();
+    return (lower === "bash" ||
+        lower === "shell" ||
+        lower === "exec" ||
+        lower === "execute" ||
+        lower === "command" ||
+        lower === "run");
+}
+function extractHost(url) {
+    try {
+        return new URL(url).host;
+    }
+    catch {
+        // Some agents pass `host:port/path` without scheme. Try to recover the host.
+        const match = /^([^/?#:]+)(?::\d+)?/.exec(url);
+        return match ? match[1] : undefined;
+    }
+}