@orlan-maker/cli 0.1.0

package/dist/config.js

@@ -0,0 +1,55 @@
+/**
+ * What the CLI keeps between commands, in the user config folder: the server, who signed in, and the
+ * agents it connected. The secrets are not in this file: they go to the OS keychain (secrets.ts).
+ */
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import path from "node:path";
+/** The server when neither --server nor ORLAN_SERVER names one. */
+export const DEFAULT_SERVER = "https://orlan.app";
+/** $ORLAN_CONFIG_DIR, else the platform's user config folder. */
+export function configDir(env = process.env) {
+    if (env.ORLAN_CONFIG_DIR)
+        return env.ORLAN_CONFIG_DIR;
+    if (process.platform === "win32" && env.APPDATA)
+        return path.join(env.APPDATA, "orlan");
+    return path.join(env.XDG_CONFIG_HOME || path.join(homedir(), ".config"), "orlan");
+}
+const configFile = () => path.join(configDir(), "config.json");
+/** The origin of a server address: https://orlan.app/ and https://orlan.app/t/1 are the same server. */
+export function serverOrigin(server) {
+    let url;
+    try {
+        url = new URL(server);
+    }
+    catch {
+        throw new Error(`"${server}" is not a server address. Use a full address, for example https://orlan.app.`);
+    }
+    if (url.protocol !== "https:" && url.protocol !== "http:") {
+        throw new Error(`"${server}" is not an http or https address.`);
+    }
+    return url.origin;
+}
+export async function readConfig() {
+    let saved = {};
+    try {
+        saved = JSON.parse(await readFile(configFile(), "utf8"));
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+    return {
+        ...saved,
+        server: serverOrigin(process.env.ORLAN_SERVER || saved.server || DEFAULT_SERVER),
+        agents: saved.agents ?? {},
+    };
+}
+/** Writes the whole file at once, so a stopped command never leaves half a file. */
+export async function writeConfig(config) {
+    const file = configFile();
+    await mkdir(path.dirname(file), { recursive: true, mode: 0o700 });
+    const temporary = `${file}.${process.pid}.tmp`;
+    await writeFile(temporary, `${JSON.stringify(config, null, 2)}\n`, { mode: 0o600 });
+    await rename(temporary, file);
+}

package/dist/http.js

@@ -0,0 +1,156 @@
+/** Calls to the Orlan API, and the one error type every command prints. */
+/**
+ * A failure the CLI explains to the person. `code` is the API's named error, when there is one.
+ * `next` is what to do next: main.ts prints it as the next_step line.
+ */
+export class OrlanError extends Error {
+    code;
+    next;
+    constructor(message, code, next) {
+        super(message);
+        this.code = code;
+        this.next = next ?? (code ? nextSteps[code] : undefined);
+    }
+}
+/** What a named API error means for a person at the terminal. */
+const explained = {
+    not_signed_in: "Orlan did not accept the token. Run `orlan auth login` again.",
+    forbidden: "Your role does not allow this. An admin of the organisation connects agents.",
+    not_found: "Orlan found no such item, or your token cannot reach it.",
+    token_invalid: "Orlan needs at least one topic for the agent. Add --topic <topic id>, or sign in again and pick topics.",
+    login_denied: "The sign-in was denied in the browser.",
+    login_expired: "The sign-in code expired. Run `orlan auth login` again.",
+    login_used: "This sign-in code was already used. Run `orlan auth login` again.",
+    login_rate_limited: "Too many sign-ins from this computer in a short time. Wait 10 minutes, then try again.",
+    org_suspended: "This organisation is suspended.",
+    topic_missing: "The agent has several topics and used none yet. Add --topic <topic id>: `orlan topics list` shows them.",
+    file_too_large: "The file is larger than Orlan takes.",
+    plan_limit_agents: "The organisation uses all the agents of the Free plan. Disconnect an agent with `orlan mcp disconnect`, or ask an admin to move the organisation to Team (organisation menu, Billing).",
+    guest_account_agent_limit: "A guest account connects one agent. Disconnect it with `orlan mcp disconnect`, or add your email in Orlan (the bar at the top) to connect more.",
+    guest_account_file_limit: "A guest account holds 3 files, 25 MB in total. Add your email in Orlan (the bar at the top) to upload more.",
+};
+/** What to do after a named API error (F038): every error ends with a next_step line. */
+const nextSteps = {
+    not_signed_in: "orlan auth login, then orlan mcp connect --agent <id>",
+    forbidden: "ask an admin of the organisation, or tell your person what you wanted to do",
+    not_found: "orlan brief (the topics, files and requests your token can reach)",
+    ref_ambiguous: "give the id from the list above, or add --topic <topic>",
+    input_invalid: "fix the input above; `orlan <command> --help` shows the options",
+    token_invalid: "orlan auth login, and pick topics for the agent",
+    login_denied: "orlan auth login",
+    login_expired: "orlan auth login",
+    login_used: "orlan auth login",
+    login_rate_limited: "wait 10 minutes, then orlan auth login",
+    org_suspended: "ask an admin of the organisation to contact Orlan",
+    topic_missing: "add --topic <topic>: orlan topics list shows them",
+    file_too_large: "make the file smaller, then run the command again",
+    file_missing: "give a file that is not empty",
+    name_invalid: "give the file a name with its extension, for example deck.pptx",
+    board_full: "ask a person to make room on the board",
+    stale_base: "orlan files pull <file> --edit, make your change on the newer version, then post it again",
+    base_invalid: "give --base a version of the file: orlan files list shows them",
+    request_done: "orlan wait (the next request)",
+    request_stopped: "stop the work on this request, and tell your person that a person stopped it on Orlan",
+    file_target_missing: "add --to <file>",
+    file_target_ambiguous: "add --to <file>",
+    upload_invalid: "run the command again: it sends the file again",
+    upload_expired: "run the command again: it sends the file again",
+    mention_invalid: "write the comment without that mention",
+    plan_limit_agents: "orlan mcp disconnect --agent <id>, or ask an admin to move the organisation to Team",
+    guest_account_agent_limit: "orlan mcp disconnect --agent <id>, or add your email in Orlan",
+    guest_account_file_limit: "add your email in Orlan (the bar at the top)",
+    internal_error: "run the command again; when it fails again, tell your person",
+};
+export async function apiCall(server, pathname, init = {}) {
+    let response;
+    try {
+        response = await fetch(new URL(pathname, server), {
+            method: init.method ?? (init.body === undefined ? "GET" : "POST"),
+            headers: {
+                ...(init.token ? { authorization: `Bearer ${init.token}` } : {}),
+                ...(init.body === undefined ? {} : { "content-type": "application/json" }),
+            },
+            body: init.body === undefined ? undefined : JSON.stringify(init.body),
+        });
+    }
+    catch (error) {
+        throw unreachable(server, error);
+    }
+    const json = (await response.json().catch(() => undefined));
+    if (!response.ok)
+        throw apiError(response.status, json?.error);
+    return json;
+}
+/** The error of a server that did not answer. */
+export function unreachable(server, error) {
+    return new OrlanError(`Orlan at ${server} did not answer: ${error.message}.`, undefined, "check the network and the server (orlan status), then run the command again");
+}
+/** The error of a refused API call, explained when the code has an explanation. */
+export function apiError(status, code) {
+    return new OrlanError((code && explained[code]) ?? `Orlan answered ${status}${code ? ` (${code})` : ""}.`, code);
+}
+/** The error of an agent token that Orlan did not accept: revoked or replaced. */
+export const agentTokenRefused = () => new OrlanError("Orlan did not accept the agent token. It was revoked or replaced.", "not_signed_in", "orlan mcp connect --agent <id>");
+/**
+ * The stateless calls of the daily commands (F038): each is one plain HTTP request with the agent
+ * token. No MCP session: no initialize, no DELETE, no session row. Orlan writes each call in the
+ * audit log like any agent call. Human ids (#12, v5, a file or topic name) work as input.
+ */
+export class AgentApi {
+    server;
+    /** The agent token: the file downloads send it as their Bearer header too. */
+    token;
+    constructor(server, token) {
+        this.server = server;
+        this.token = token;
+    }
+    async send(url, init, what) {
+        let response;
+        try {
+            response = await fetch(url, { ...init, headers: { authorization: `Bearer ${this.token}`, ...init.headers } });
+        }
+        catch (error) {
+            throw unreachable(this.server, error);
+        }
+        if (response.status === 401)
+            throw agentTokenRefused();
+        const json = (await response.json().catch(() => undefined));
+        if (!response.ok) {
+            const code = json?.error;
+            // A detail can end with Orlan's own next_step line: that is the next step.
+            const [detail, next] = (json?.detail ?? "").split(/\n?next_step: /);
+            // With no detail, a known code has its explanation.
+            const message = !detail && code && explained[code]
+                ? explained[code]
+                : `Orlan refused ${what}: ${code ? `${code}${detail ? `. ${detail}` : ""}` : `answered ${response.status}`}`;
+            throw new OrlanError(message, code, next || undefined);
+        }
+        return json;
+    }
+    /** Calls an agent tool with its input and returns its JSON answer. A refusal throws with its code. */
+    call(tool, input = {}) {
+        return this.send(new URL(`/api/agent/tools/${encodeURIComponent(tool)}`, this.server), { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(input) }, tool);
+    }
+    /** GET an agent route, with its query. */
+    get(pathname, query, what) {
+        return this.send(this.url(pathname, query), {}, what);
+    }
+    /** POST a local file as the raw body of an agent route, with its query. */
+    postFile(pathname, query, body, what) {
+        return this.send(this.url(pathname, query), { method: "POST", headers: { "content-type": "application/octet-stream" }, body: new Uint8Array(body) }, what);
+    }
+    /**
+     * Sends a local file in one request and returns its upload id, for post or respond. The
+     * file goes to the topic of the target: a file (a version of it), a request (its answer), or a topic.
+     */
+    async upload(body, target, what = "the upload") {
+        return (await this.postFile("/api/agent/uploads", target, body, what)).uploadId;
+    }
+    url(pathname, query) {
+        const url = new URL(pathname, this.server);
+        for (const [key, value] of Object.entries(query))
+            if (value)
+                url.searchParams.set(key, value);
+        return url;
+    }
+}

package/dist/main.js

@@ -0,0 +1,114 @@
+#!/usr/bin/env node
+/**
+ * The orlan command (F026, decision D023). `orlan help` lists the commands; `orlan <command> --help`
+ * shows one.
+ */
+import { readFileSync, realpathSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { parseArgs } from "node:util";
+import { commands } from "./commands.js";
+import { OrlanError } from "./http.js";
+const { version } = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+function overview() {
+    const width = Math.max(...Object.keys(commands).map((name) => name.length));
+    return [
+        "orlan - connect an agent to Orlan, and work with its topics, files and comments.",
+        "",
+        "Set up:",
+        "  npm i -g @orlan-maker/cli",
+        "  orlan auth login",
+        "  orlan skills add --agent <id>",
+        "  orlan mcp connect --agent <id>",
+        "",
+        "Commands:",
+        ...Object.entries(commands).map(([name, command]) => `  ${name.padEnd(width)}  ${command.summary}`),
+        "",
+        "Agents: claude-code, codex, cursor, opencode, other.",
+        "Run `orlan <command> --help` for the options of a command. `orlan --version` prints the version.",
+    ].join("\n");
+}
+function commandHelp(command) {
+    return [
+        `Usage: ${command.usage}`,
+        "",
+        command.summary,
+        ...(command.details.length ? ["", ...command.details] : []),
+    ].join("\n");
+}
+/** Finds the command the arguments name: one word ("status") or two ("auth login"). */
+function findCommand(args) {
+    const two = args.slice(0, 2).join(" ");
+    if (commands[two])
+        return { name: two, rest: args.slice(2) };
+    const one = args[0] ?? "";
+    if (commands[one])
+        return { name: one, rest: args.slice(1) };
+    return undefined;
+}
+/** Runs the command line and returns the exit code. */
+export async function main(args, io) {
+    if (args.length === 0 || args[0] === "help" || args[0] === "--help" || args[0] === "-h") {
+        const asked = args[0] === "help" ? findCommand(args.slice(1)) : undefined;
+        io.out(asked ? commandHelp(commands[asked.name]) : overview());
+        return 0;
+    }
+    if (args[0] === "--version" || args[0] === "-v") {
+        io.out(io.version);
+        return 0;
+    }
+    const found = findCommand(args);
+    if (!found) {
+        const group = Object.keys(commands).filter((name) => name.startsWith(`${args[0]} `));
+        process.stderr.write(group.length
+            ? `orlan: "${args.join(" ")}" needs one of: ${group.join(", ")}.\nnext_step: orlan help\n`
+            : `orlan: there is no command "${args[0]}".\nnext_step: orlan help\n`);
+        return 2;
+    }
+    const command = commands[found.name];
+    if (found.rest.includes("--help") || found.rest.includes("-h")) {
+        io.out(commandHelp(command));
+        return 0;
+    }
+    const help = `orlan ${found.name} --help`;
+    let parsed;
+    try {
+        parsed = parseArgs({ args: found.rest, options: command.options, allowPositionals: true, strict: true });
+    }
+    catch (error) {
+        process.stderr.write(`orlan: ${error.message}\nUsage: ${command.usage}\nnext_step: ${help}\n`);
+        return 2;
+    }
+    const [least, most] = command.positionals;
+    if (parsed.positionals.length < least || parsed.positionals.length > most) {
+        process.stderr.write(`orlan: wrong arguments.\nUsage: ${command.usage}\nnext_step: ${help}\n`);
+        return 2;
+    }
+    try {
+        return (await command.run(parsed.values, parsed.positionals, io)) ?? 0;
+    }
+    catch (error) {
+        const missing = error.code === "ENOENT";
+        if (!(error instanceof OrlanError) && !missing)
+            throw error;
+        // Every error says what to do next (F038). With --json it is JSON, like the answer.
+        const next = (error instanceof OrlanError ? error.next : undefined) ??
+            (missing ? "check the path, then run the command again" : help);
+        const code = error instanceof OrlanError ? error.code : "file_missing";
+        if (parsed.values.json) {
+            io.out(JSON.stringify({ error: code ?? "failed", message: error.message, next_step: next }));
+        }
+        else {
+            process.stderr.write(`orlan: ${error.message}\nnext_step: ${next}\n`);
+        }
+        return 1;
+    }
+}
+// Runs only as the program, not when a test imports main(). npm starts it through a link, so compare real paths.
+const entry = process.argv[1];
+if (entry && realpathSync(entry) === realpathSync(fileURLToPath(import.meta.url))) {
+    process.exitCode = await main(process.argv.slice(2), {
+        out: (line) => process.stdout.write(`${line}\n`),
+        flushed: () => new Promise((resolve) => process.stdout.write("", () => resolve())),
+        version,
+    });
+}

package/dist/mcp.js

@@ -0,0 +1,113 @@
+/**
+ * A small MCP client over Streamable HTTP, for the MCP test of `orlan status` and `orlan mcp connect`:
+ * it proves that the agent's MCP server works. The daily commands use plain HTTP (AgentApi, F038). A
+ * test is one MCP session of the agent token: it starts the session, calls its tool, and closes it. The
+ * client names itself "orlan-cli", so Orlan keeps these sessions off the Agents tab and sends no
+ * "session ended" notification for them. Every call is in the audit log like any agent call.
+ */
+import { OrlanError } from "./http.js";
+const PROTOCOL_VERSION = "2025-06-18";
+/** The JSON-RPC answer with this id, from a JSON body or from a server-sent event stream. */
+async function answerOf(response, id) {
+    const text = await response.text();
+    const type = response.headers.get("content-type") ?? "";
+    const messages = type.includes("text/event-stream")
+        ? text
+            .split(/\r?\n\r?\n/)
+            .map((event) => event
+            .split(/\r?\n/)
+            .filter((line) => line.startsWith("data:"))
+            .map((line) => line.slice(5).trimStart())
+            .join("\n"))
+            .filter((data) => data.length > 0)
+            .map((data) => JSON.parse(data))
+        : [JSON.parse(text)];
+    const answer = messages.find((message) => message.id === id);
+    if (!answer)
+        throw new OrlanError("Orlan's MCP server gave no answer.");
+    if (answer.error)
+        throw new OrlanError(`Orlan's MCP server refused the call: ${answer.error.message}`);
+    return answer;
+}
+export class McpClient {
+    sessionId;
+    nextId = 1;
+    url;
+    /** The agent token: the file downloads send it as their Bearer header too. */
+    token;
+    version;
+    constructor(server, token, version) {
+        this.url = new URL("/mcp", server);
+        this.token = token;
+        this.version = version;
+    }
+    async post(body) {
+        let response;
+        try {
+            response = await fetch(this.url, {
+                method: "POST",
+                headers: {
+                    authorization: `Bearer ${this.token}`,
+                    "content-type": "application/json",
+                    accept: "application/json, text/event-stream",
+                    ...(this.sessionId ? { "mcp-session-id": this.sessionId, "mcp-protocol-version": PROTOCOL_VERSION } : {}),
+                },
+                body: JSON.stringify(body),
+            });
+        }
+        catch (error) {
+            throw new OrlanError(`Orlan's MCP server at ${this.url} did not answer: ${error.message}.`);
+        }
+        if (response.status === 401) {
+            throw new OrlanError("Orlan did not accept the agent token. It was revoked or replaced: run `orlan mcp connect` again.", "not_signed_in");
+        }
+        if (!response.ok && response.status !== 202) {
+            throw new OrlanError(`Orlan's MCP server answered ${response.status}.`);
+        }
+        return response;
+    }
+    async request(method, params) {
+        const id = this.nextId++;
+        const response = await this.post({ jsonrpc: "2.0", id, method, params });
+        if (method === "initialize")
+            this.sessionId = response.headers.get("mcp-session-id") ?? undefined;
+        return (await answerOf(response, id)).result;
+    }
+    async open() {
+        await this.request("initialize", {
+            protocolVersion: PROTOCOL_VERSION,
+            capabilities: {},
+            clientInfo: { name: "orlan-cli", version: this.version },
+        });
+        if (!this.sessionId)
+            throw new OrlanError("Orlan's MCP server started no session.");
+        await (await this.post({ jsonrpc: "2.0", method: "notifications/initialized" })).text();
+    }
+    /** Calls a tool and returns its JSON answer. A refusal ("Refused: <code>") throws with that code. */
+    async call(tool, args = {}) {
+        if (!this.sessionId)
+            await this.open();
+        const result = (await this.request("tools/call", { name: tool, arguments: args }));
+        const text = result.content?.find((part) => part.type === "text")?.text ?? "";
+        if (result.isError) {
+            const code = /^Refused: ([a-z_]+)/.exec(text)?.[1];
+            throw new OrlanError(`Orlan refused ${tool}: ${text.replace(/^Refused: /, "")}`, code);
+        }
+        return JSON.parse(text);
+    }
+    /** Ends the session (HTTP DELETE). */
+    async close() {
+        if (!this.sessionId)
+            return;
+        const sessionId = this.sessionId;
+        this.sessionId = undefined;
+        await fetch(this.url, {
+            method: "DELETE",
+            headers: {
+                authorization: `Bearer ${this.token}`,
+                "mcp-session-id": sessionId,
+                "mcp-protocol-version": PROTOCOL_VERSION,
+            },
+        }).catch(() => undefined);
+    }
+}

package/dist/secrets.js

@@ -0,0 +1,120 @@
+/**
+ * The CLI token and the agent tokens. They go to the OS keychain when there is one: the macOS
+ * keychain (`security`), or the Secret Service on Linux (`secret-tool`). Else, or with
+ * ORLAN_KEYCHAIN=off, to credentials.json in the config folder, readable by this user only (0600).
+ * A secret never goes on a command line: both keychain tools read it from standard input.
+ */
+import { spawn } from "node:child_process";
+import { chmod, mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { configDir } from "./config.js";
+const SERVICE = "orlan";
+/** The account name of a secret: the server and what it is for, for example "https://orlan.app#cli". */
+export const account = (server, name) => `${server}#${name}`;
+function run(command, args, input) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(command, args, { stdio: ["pipe", "pipe", "ignore"] });
+        let stdout = "";
+        child.stdout.on("data", (chunk) => {
+            stdout += chunk.toString("utf8");
+        });
+        child.on("error", reject);
+        child.on("close", (code) => resolve({ code: code ?? 1, stdout }));
+        child.stdin.end(input ?? "");
+    });
+}
+/** Only these characters reach a keychain command, so no quoting can break. */
+const safe = (value) => {
+    if (!/^[A-Za-z0-9_\-.:/#]+$/.test(value))
+        throw new Error(`Orlan cannot store "${value}" in the keychain.`);
+    return value;
+};
+const macKeychain = {
+    // `security -i` reads its commands from standard input, so the secret is not in the process list.
+    set: async (name, secret) => (await run("/usr/bin/security", ["-i"], `add-generic-password -U -s ${SERVICE} -a "${safe(name)}" -l "Orlan CLI" -w "${safe(secret)}"\n`)).code === 0,
+    get: async (name) => {
+        const found = await run("/usr/bin/security", ["find-generic-password", "-s", SERVICE, "-a", safe(name), "-w"]);
+        return found.code === 0 ? found.stdout.trim() || undefined : undefined;
+    },
+    delete: async (name) => {
+        await run("/usr/bin/security", ["delete-generic-password", "-s", SERVICE, "-a", safe(name)]);
+    },
+};
+const secretService = {
+    set: async (name, secret) => (await run("secret-tool", ["store", "--label=Orlan CLI", "service", SERVICE, "account", name], secret)).code === 0,
+    get: async (name) => {
+        const found = await run("secret-tool", ["lookup", "service", SERVICE, "account", name]);
+        return found.code === 0 ? found.stdout.trim() || undefined : undefined;
+    },
+    delete: async (name) => {
+        await run("secret-tool", ["clear", "service", SERVICE, "account", name]);
+    },
+};
+function keychain() {
+    if (process.env.ORLAN_KEYCHAIN === "off")
+        return undefined;
+    if (process.platform === "darwin")
+        return macKeychain;
+    if (process.platform === "linux")
+        return secretService;
+    return undefined;
+}
+/** A keychain call that fails to start (no secret-tool, no D-Bus session) counts as no keychain. */
+async function tryKeychain(work) {
+    const chain = keychain();
+    if (!chain)
+        return undefined;
+    try {
+        return await work(chain);
+    }
+    catch {
+        return undefined;
+    }
+}
+const credentialsFile = () => path.join(configDir(), "credentials.json");
+async function readFileStore() {
+    try {
+        return JSON.parse(await readFile(credentialsFile(), "utf8"));
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return {};
+        throw error;
+    }
+}
+async function writeFileStore(store) {
+    const file = credentialsFile();
+    await mkdir(path.dirname(file), { recursive: true, mode: 0o700 });
+    const temporary = `${file}.${process.pid}.tmp`;
+    await writeFile(temporary, `${JSON.stringify(store, null, 2)}\n`, { mode: 0o600 });
+    await chmod(temporary, 0o600);
+    await rename(temporary, file);
+}
+/** Stores a secret. Returns where it went. */
+export async function setSecret(name, secret) {
+    // Read back: `security -i` can end with 0 when its command failed.
+    const stored = await tryKeychain(async (chain) => (await chain.set(name, secret)) && (await chain.get(name)) === secret);
+    const store = await readFileStore();
+    if (stored) {
+        // An older copy in the file would outlive the keychain entry.
+        if (name in store) {
+            delete store[name];
+            await writeFileStore(store);
+        }
+        return "keychain";
+    }
+    store[name] = secret;
+    await writeFileStore(store);
+    return "file";
+}
+export async function getSecret(name) {
+    return (await tryKeychain((chain) => chain.get(name))) ?? (await readFileStore())[name];
+}
+export async function deleteSecret(name) {
+    await tryKeychain((chain) => chain.delete(name));
+    const store = await readFileStore();
+    if (name in store) {
+        delete store[name];
+        await writeFileStore(store);
+    }
+}

package/dist/skills.js

@@ -0,0 +1,20 @@
+/**
+ * The Orlan skills `orlan skills add` writes where an agent reads skills. Each is a SKILL.md in the
+ * package's skills/ folder, the same files the Claude Code plugin loads (F044).
+ */
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { skillsDir } from "./agents.js";
+export const skillNames = ["orlan-review", "orlan-versions"];
+/** Writes every Orlan skill for the agent. Returns the folders it wrote. */
+export async function writeSkills(agent, cwd = process.cwd()) {
+    const root = skillsDir(agent, cwd);
+    const written = [];
+    for (const name of skillNames) {
+        const folder = path.join(root, name);
+        await mkdir(folder, { recursive: true });
+        await writeFile(path.join(folder, "SKILL.md"), await readFile(new URL(`../skills/${name}/SKILL.md`, import.meta.url), "utf8"));
+        written.push(folder);
+    }
+    return written;
+}

package/hooks/hooks.json

@@ -0,0 +1,68 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/session-start", "args": [] }]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/bin/orlan",
+            "args": ["hook", "working", "--agent", "claude-code"],
+            "async": true
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/bin/orlan",
+            "args": ["hook", "working", "--agent", "claude-code"],
+            "async": true
+          }
+        ]
+      }
+    ],
+    "Notification": [
+      {
+        "matcher": "permission_prompt|agent_needs_input",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/bin/orlan",
+            "args": ["hook", "needs-input", "--agent", "claude-code"]
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/bin/orlan",
+            "args": ["hook", "idle", "--agent", "claude-code"]
+          }
+        ]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/bin/orlan",
+            "args": ["hook", "done", "--agent", "claude-code"],
+            "timeout": 5
+          }
+        ]
+      }
+    ]
+  }
+}

package/hooks/session-start

@@ -0,0 +1,11 @@
+#!/bin/sh
+# SessionStart hook of the Orlan plugin (F044). The board shows the session as working, and the brief
+# goes into the session's context (the output of a SessionStart hook does). An error of the brief goes
+# there too, for example "No agent is connected", so the agent can tell the person what to do.
+orlan="$CLAUDE_PLUGIN_ROOT/bin/orlan"
+"$orlan" hook working --agent claude-code
+if "$orlan" brief --agent claude-code 2>&1; then
+  echo "The Orlan plugin's monitor runs orlan wait --follow for this session: each request comes as a notification. Do not run orlan wait yourself."
+  echo "Answer a request with the orlan command in few steps: orlan files pull <file id> --out <path> && cat <path>; edit the file; orlan respond <request id> --file <path> [--to <file id>] --message \"<what changed>\"."
+fi
+exit 0

package/monitors/monitors.json

@@ -0,0 +1,7 @@
+[
+  {
+    "name": "orlan-requests",
+    "command": "\"${CLAUDE_PLUGIN_ROOT}/bin/orlan\" wait --follow --agent claude-code",
+    "description": "Orlan requests: a mention of this agent on the board"
+  }
+]