@rudderhq/server 0.7.11 → 0.7.13

package/dist/services/workspace-manifest-native.js

@@ -0,0 +1,219 @@
+import { resolveNativeCommand } from "@rudderhq/agent-runtime-utils";
+import { resolveRudderNativeCapability, resolveRudderNativeTarget } from "@rudderhq/shared";
+import { spawn } from "node:child_process";
+import { createHash } from "node:crypto";
+import { existsSync } from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+import readline from "node:readline";
+import { fileURLToPath } from "node:url";
+import { resolveRudderInstanceRoot } from "../home-paths.js";
+const PROTOCOL_VERSION = 1;
+const MAX_ENTRIES = 1_000_000;
+const MAX_PATH_BYTES = 128 * 1024 * 1024;
+const MAX_MANIFEST_BYTES = 256 * 1024 * 1024;
+const DEBOUNCE_MS = 100;
+const REQUIRED_READY_TIMEOUT_MS = 5_000;
+const sessions = new Map();
+class NativeWorkspaceManifestError extends Error {
+    diagnostic;
+    constructor(session, code, detail) {
+        super(detail);
+        this.name = "NativeWorkspaceManifestError";
+        this.diagnostic = {
+            capability: "workspace-manifest",
+            target: session.target,
+            binaryVersion: session.binaryVersion,
+            protocolVersion: String(PROTOCOL_VERSION),
+            effectiveEngine: "rust",
+            fallbackCode: code,
+        };
+    }
+}
+function nativeTarget() {
+    return resolveRudderNativeTarget();
+}
+export function resolveNativeWorkspaceManifestBinary() {
+    const configured = process.env.RUDDER_NATIVE_WORKSPACE_MANIFEST_PATH?.trim()
+        || process.env.RUDDER_NATIVE_PATH?.trim();
+    if (configured)
+        return path.resolve(configured);
+    const binaryName = process.platform === "win32" ? "rudder-native.exe" : "rudder-native";
+    const moduleDir = path.dirname(fileURLToPath(import.meta.url));
+    const target = nativeTarget();
+    const resourcesPath = process.env.RUDDER_DESKTOP_RESOURCES_PATH?.trim()
+        || (typeof process.resourcesPath === "string"
+            ? process.resourcesPath
+            : "");
+    const candidates = [
+        path.resolve(moduleDir, "../../../native/target/debug", binaryName),
+        path.resolve(moduleDir, "../../../../native/target/debug", binaryName),
+        path.resolve(moduleDir, "../../../native", target ?? "unsupported", binaryName),
+        resourcesPath && target ? path.resolve(resourcesPath, "native", target, binaryName) : "",
+    ].filter(Boolean);
+    return candidates.find((candidate) => existsSync(candidate)) ?? candidates[0];
+}
+function manifestPathForRoot(rootPath) {
+    const key = createHash("sha256").update(path.resolve(rootPath)).digest("hex").slice(0, 24);
+    return path.resolve(resolveRudderInstanceRoot(), "data", "native-workspace-manifests", `${key}.json`);
+}
+function watchState(value) {
+    return ["building", "ready", "dirty", "overflow", "unavailable", "stopped"].includes(String(value))
+        ? value
+        : null;
+}
+async function startSession(rootPath) {
+    const manifestPath = manifestPathForRoot(rootPath);
+    await fs.mkdir(path.dirname(manifestPath), { recursive: true });
+    const command = resolveNativeCommand(resolveNativeWorkspaceManifestBinary(), [
+        "workspace", "watch", path.resolve(rootPath), manifestPath,
+        String(MAX_ENTRIES), String(MAX_PATH_BYTES), String(DEBOUNCE_MS),
+    ]);
+    const child = spawn(command.command, command.args, { stdio: ["pipe", "pipe", "pipe"], windowsHide: true });
+    const session = {
+        child, manifestPath, state: "building", exited: false,
+        target: nativeTarget() ?? "unsupported", binaryVersion: "unavailable",
+    };
+    const lines = readline.createInterface({ input: child.stdout });
+    lines.on("line", (line) => {
+        try {
+            const envelope = JSON.parse(line);
+            const state = watchState(envelope.state);
+            if (envelope.ok !== true || envelope.capability !== "workspace.watch"
+                || envelope.protocolVersion !== PROTOCOL_VERSION || !state) {
+                session.state = "unavailable";
+                return;
+            }
+            if (typeof envelope.target === "string")
+                session.target = envelope.target;
+            if (typeof envelope.binaryVersion === "string")
+                session.binaryVersion = envelope.binaryVersion;
+            session.state = state;
+        }
+        catch {
+            session.state = "unavailable";
+        }
+    });
+    child.once("error", () => {
+        session.state = "unavailable";
+        session.exited = true;
+    });
+    child.once("exit", () => {
+        if (session.state !== "stopped")
+            session.state = "unavailable";
+        session.exited = true;
+    });
+    child.stderr.resume();
+    return session;
+}
+async function ensureSession(rootPath) {
+    const key = path.resolve(rootPath);
+    const existing = sessions.get(key);
+    if (existing && !existing.exited)
+        return existing;
+    const session = await startSession(key);
+    sessions.set(key, session);
+    return session;
+}
+async function waitForRequiredReady(session) {
+    const deadline = Date.now() + REQUIRED_READY_TIMEOUT_MS;
+    while (session.state !== "ready") {
+        if (session.state === "unavailable" || session.exited) {
+            throw new NativeWorkspaceManifestError(session, "watch_unavailable", "Native workspace manifest watcher is unavailable");
+        }
+        if (Date.now() >= deadline) {
+            throw new NativeWorkspaceManifestError(session, "ready_timeout", `Native workspace manifest watcher did not become ready within ${REQUIRED_READY_TIMEOUT_MS}ms`);
+        }
+        await new Promise((resolve) => setTimeout(resolve, 10));
+    }
+}
+function parseManifest(value, rootPath) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return null;
+    const manifest = value;
+    if (manifest.protocolVersion !== PROTOCOL_VERSION || manifest.state !== "ready"
+        || path.resolve(String(manifest.rootPath ?? "")) !== path.resolve(rootPath)
+        || !Array.isArray(manifest.entries) || manifest.entries.length > MAX_ENTRIES)
+        return null;
+    const entries = [];
+    let pathBytes = 0;
+    for (const value of manifest.entries) {
+        if (!value || typeof value !== "object" || Array.isArray(value))
+            return null;
+        const entry = value;
+        const entryPath = typeof entry.path === "string" ? entry.path : "";
+        const kind = entry.kind;
+        if (!entryPath || entryPath.includes("\\") || entryPath.startsWith("/")
+            || entryPath.split("/").some((part) => !part || part === "." || part === "..")
+            || !["file", "directory", "symlink"].includes(String(kind))
+            || !Number.isSafeInteger(entry.byteSize) || Number(entry.byteSize) < 0
+            || !Number.isSafeInteger(entry.modifiedMillis) || Number(entry.modifiedMillis) < 0)
+            return null;
+        pathBytes += Buffer.byteLength(entryPath);
+        if (pathBytes > MAX_PATH_BYTES)
+            return null;
+        entries.push({
+            path: entryPath,
+            kind: kind,
+            byteSize: Number(entry.byteSize),
+            modifiedMillis: Number(entry.modifiedMillis),
+        });
+    }
+    return entries;
+}
+export async function readNativeWorkspaceManifest(rootPath) {
+    const policy = resolveRudderNativeCapability({ capability: "workspace-manifest", env: process.env });
+    if (!policy.enabled)
+        return null;
+    let session;
+    try {
+        session = await ensureSession(rootPath);
+    }
+    catch (error) {
+        if (policy.required)
+            throw error;
+        return null;
+    }
+    if (policy.required)
+        await waitForRequiredReady(session);
+    if (session.state !== "ready") {
+        return null;
+    }
+    try {
+        const stat = await fs.stat(session.manifestPath);
+        if (!stat.isFile() || stat.size > MAX_MANIFEST_BYTES)
+            throw new Error("Native workspace manifest exceeds its read boundary");
+        const entries = parseManifest(JSON.parse(await fs.readFile(session.manifestPath, "utf8")), rootPath);
+        if (!entries)
+            throw new Error("Native workspace manifest is invalid");
+        return entries;
+    }
+    catch (error) {
+        await fs.rm(session.manifestPath, { force: true }).catch(() => undefined);
+        session.state = "dirty";
+        if (policy.required) {
+            throw new NativeWorkspaceManifestError(session, "invalid_manifest", error instanceof Error ? error.message : "Native workspace manifest is invalid");
+        }
+        return null;
+    }
+}
+export async function stopNativeWorkspaceManifestWatchersForTests() {
+    const active = [...sessions.values()];
+    sessions.clear();
+    await Promise.all(active.map(async (session) => {
+        if (session.exited)
+            return;
+        session.child.stdin.end();
+        await new Promise((resolve) => {
+            const timer = setTimeout(() => {
+                session.child.kill();
+                resolve();
+            }, 1_000);
+            session.child.once("exit", () => {
+                clearTimeout(timer);
+                resolve();
+            });
+        });
+    }));
+}
+//# sourceMappingURL=workspace-manifest-native.js.map

package/dist/services/workspace-manifest-native.js.map

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

package/dist/services/workspace-restore-reconciliation.d.ts

@@ -0,0 +1,11 @@
+import { type Db } from "@rudderhq/db";
+/** Reconcile only validated receipts and their exact operation-owned roots. */
+export declare function reconcileWorkspaceRestoreReceipts(db?: Db): Promise<{
+    recovered: string[];
+    blocked: Array<{
+        receiptPath: string;
+        operationId: string;
+        error: string;
+    }>;
+}>;
+//# sourceMappingURL=workspace-restore-reconciliation.d.ts.map

package/dist/services/workspace-restore-reconciliation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace-restore-reconciliation.d.ts","sourceRoot":"","sources":["../../src/services/workspace-restore-reconciliation.ts"],"names":[],"mappings":"AAAA,OAAO,EAAoB,KAAK,EAAE,EAAE,MAAM,cAAc,CAAC;AAgDzD,+EAA+E;AAC/E,wBAAsB,iCAAiC,CAAC,EAAE,CAAC,EAAE,EAAE,GAAG,OAAO,CAAC;IACxE,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,OAAO,EAAE,KAAK,CAAC;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAC7E,CAAC,CA+ED"}

package/dist/services/workspace-restore-reconciliation.js

@@ -0,0 +1,165 @@
+import { workspaceBackups } from "@rudderhq/db";
+import { and, eq } from "drizzle-orm";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { resolveDefaultBackupDir, resolveOrganizationWorkspaceRoot } from "../home-paths.js";
+import { walkWorkspaceBackupV2 } from "./workspace-backup-v2.js";
+async function pathExists(targetPath) {
+    return fs.lstat(targetPath).catch((error) => {
+        if (error.code === "ENOENT")
+            return null;
+        throw error;
+    });
+}
+async function syncDirectory(directoryPath) {
+    const handle = await fs.open(directoryPath, "r");
+    try {
+        if (process.platform !== "win32")
+            await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+}
+async function workspaceTreeSha256(rootPath) {
+    return (await walkWorkspaceBackupV2(rootPath)).treeSha256;
+}
+async function readRestoreReceipt(filePath) {
+    try {
+        const value = JSON.parse(await fs.readFile(filePath, "utf8"));
+        if (value.version !== 1 || typeof value.operationId !== "string" || typeof value.orgId !== "string"
+            || typeof value.backupId !== "string"
+            || !["prepared", "live_moved", "committed", "rolled_back", "recovery_required"].includes(value.phase ?? "")
+            || typeof value.workspaceRoot !== "string" || typeof value.stagingRoot !== "string"
+            || typeof value.rollbackRoot !== "string"
+            || (value.liveTreeSha256 !== null && typeof value.liveTreeSha256 !== "string")
+            || typeof value.stagingTreeSha256 !== "string"
+            || (value.expectedTreeSha256 !== null && typeof value.expectedTreeSha256 !== "string")
+            || typeof value.preRestoreBackupId !== "string")
+            return null;
+        return value;
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return null;
+        throw error;
+    }
+}
+function isOwnedRestoreRoot(root, workspaceRoot, operationId, kind) {
+    return path.resolve(root) !== path.resolve(workspaceRoot)
+        && path.resolve(root) === path.resolve(path.dirname(workspaceRoot), `.rudder-workspace-restore-${kind}-${operationId}`);
+}
+/** Reconcile only validated receipts and their exact operation-owned roots. */
+export async function reconcileWorkspaceRestoreReceipts(db) {
+    const receiptRoot = path.resolve(resolveDefaultBackupDir(), "workspace-restore-receipts");
+    const recovered = [];
+    const blocked = [];
+    let names;
+    try {
+        names = await fs.readdir(receiptRoot);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return { recovered, blocked };
+        throw error;
+    }
+    for (const name of names.filter((entry) => entry.endsWith(".json"))) {
+        const receiptPath = path.join(receiptRoot, name);
+        let receipt = null;
+        try {
+            receipt = await readRestoreReceipt(receiptPath);
+        }
+        catch (error) {
+            blocked.push({ receiptPath, operationId: "unknown", error: error instanceof Error ? error.message : String(error) });
+            continue;
+        }
+        let canonicalWorkspaceRoot = null;
+        try {
+            if (receipt?.orgId)
+                canonicalWorkspaceRoot = path.resolve(resolveOrganizationWorkspaceRoot(receipt.orgId));
+        }
+        catch {
+            canonicalWorkspaceRoot = null;
+        }
+        if (!receipt || !canonicalWorkspaceRoot
+            || !/^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/.test(receipt.operationId)
+            || path.resolve(receipt.workspaceRoot) !== canonicalWorkspaceRoot
+            || !isOwnedRestoreRoot(receipt.stagingRoot, receipt.workspaceRoot, receipt.operationId, "staging")
+            || !isOwnedRestoreRoot(receipt.rollbackRoot, receipt.workspaceRoot, receipt.operationId, "rollback")) {
+            blocked.push({ receiptPath, operationId: receipt?.operationId ?? "unknown", error: "invalid_or_unowned_receipt" });
+            continue;
+        }
+        try {
+            const workspace = await pathExists(receipt.workspaceRoot);
+            const rollback = await pathExists(receipt.rollbackRoot);
+            const expectedPublishedTree = receipt.expectedTreeSha256 ?? receipt.stagingTreeSha256;
+            let publishedRestore = false;
+            if (receipt.phase === "prepared") {
+                if (workspace && rollback)
+                    throw new Error("prepared receipt has conflicting live and rollback roots");
+                if (!workspace && rollback) {
+                    if (!receipt.liveTreeSha256 || await workspaceTreeSha256(receipt.rollbackRoot) !== receipt.liveTreeSha256)
+                        throw new Error("prepared rollback tree does not match recorded live tree");
+                    await fs.rename(receipt.rollbackRoot, receipt.workspaceRoot);
+                    await syncDirectory(path.dirname(receipt.workspaceRoot));
+                }
+            }
+            else if (receipt.phase === "committed") {
+                if (!workspace)
+                    throw new Error("committed receipt workspace is missing");
+                if (await workspaceTreeSha256(receipt.workspaceRoot) !== expectedPublishedTree) {
+                    throw new Error("committed workspace tree does not match receipt");
+                }
+                publishedRestore = true;
+            }
+            else if (receipt.phase === "rolled_back") {
+                if (!workspace)
+                    throw new Error("rolled_back receipt workspace is missing");
+                if (receipt.liveTreeSha256 && await workspaceTreeSha256(receipt.workspaceRoot) !== receipt.liveTreeSha256)
+                    throw new Error("rolled_back workspace tree does not match recorded live tree");
+            }
+            else if (receipt.phase === "live_moved" || receipt.phase === "recovery_required") {
+                if (!workspace && rollback) {
+                    if (!receipt.liveTreeSha256 || await workspaceTreeSha256(receipt.rollbackRoot) !== receipt.liveTreeSha256)
+                        throw new Error("rollback tree does not match recorded live tree");
+                    await fs.rename(receipt.rollbackRoot, receipt.workspaceRoot);
+                    await syncDirectory(path.dirname(receipt.workspaceRoot));
+                }
+                else if (workspace && !rollback) {
+                    if (await workspaceTreeSha256(receipt.workspaceRoot) !== expectedPublishedTree)
+                        throw new Error("published workspace tree does not match receipt");
+                    publishedRestore = true;
+                }
+                else if (workspace && rollback) {
+                    if (await workspaceTreeSha256(receipt.workspaceRoot) === expectedPublishedTree)
+                        publishedRestore = true;
+                    else if (receipt.liveTreeSha256 && await workspaceTreeSha256(receipt.rollbackRoot) === receipt.liveTreeSha256) {
+                        await fs.rm(receipt.workspaceRoot, { recursive: true, force: true });
+                        await fs.rename(receipt.rollbackRoot, receipt.workspaceRoot);
+                        await syncDirectory(path.dirname(receipt.workspaceRoot));
+                    }
+                    else
+                        throw new Error("workspace and rollback roots match neither recorded tree");
+                }
+                else
+                    throw new Error("workspace and rollback roots are both missing");
+            }
+            if (publishedRestore && db) {
+                const [updated] = await db.update(workspaceBackups).set({ status: "restored", updatedAt: new Date() })
+                    .where(and(eq(workspaceBackups.id, receipt.backupId), eq(workspaceBackups.orgId, receipt.orgId))).returning({ id: workspaceBackups.id });
+                if (!updated)
+                    throw new Error("restore receipt backup row is missing");
+            }
+            await fs.rm(receipt.stagingRoot, { recursive: true, force: true });
+            await fs.rm(receipt.rollbackRoot, { recursive: true, force: true });
+            await fs.rm(receiptPath, { force: true });
+            await syncDirectory(receiptRoot);
+            recovered.push(receipt.operationId);
+        }
+        catch (error) {
+            blocked.push({ receiptPath, operationId: receipt.operationId, error: error instanceof Error ? error.message : String(error) });
+        }
+    }
+    return { recovered, blocked };
+}
+//# sourceMappingURL=workspace-restore-reconciliation.js.map

package/dist/services/workspace-restore-reconciliation.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rudderhq/server",
-  "version": "0.7.11",
+  "version": "0.7.13",
   "license": "SEE LICENSE IN LICENSE",
   "homepage": "https://github.com/Undertone0809/rudder",
   "bugs": {
@@ -55,19 +55,19 @@
     "@aws-sdk/client-s3": "^3.1015.0",
     "@larksuiteoapi/node-sdk": "1.67.0",
     "@modelcontextprotocol/client": "2.0.0",
-    "@rudderhq/agent-runtime-claude-local": "0.7.11",
-    "@rudderhq/agent-runtime-codex-local": "0.7.11",
-    "@rudderhq/agent-runtime-cursor-local": "0.7.11",
-    "@rudderhq/agent-runtime-gemini-local": "0.7.11",
-    "@rudderhq/agent-runtime-hermes-gateway": "0.7.11",
-    "@rudderhq/agent-runtime-openclaw-gateway": "0.7.11",
-    "@rudderhq/agent-runtime-opencode-local": "0.7.11",
-    "@rudderhq/agent-runtime-pi-local": "0.7.11",
-    "@rudderhq/agent-runtime-utils": "0.7.11",
-    "@rudderhq/db": "0.7.11",
-    "@rudderhq/identity-core": "0.7.11",
-    "@rudderhq/run-intelligence-core": "0.7.11",
-    "@rudderhq/shared": "0.7.11",
+    "@rudderhq/agent-runtime-claude-local": "0.7.13",
+    "@rudderhq/agent-runtime-codex-local": "0.7.13",
+    "@rudderhq/agent-runtime-cursor-local": "0.7.13",
+    "@rudderhq/agent-runtime-gemini-local": "0.7.13",
+    "@rudderhq/agent-runtime-hermes-gateway": "0.7.13",
+    "@rudderhq/agent-runtime-openclaw-gateway": "0.7.13",
+    "@rudderhq/agent-runtime-opencode-local": "0.7.13",
+    "@rudderhq/agent-runtime-pi-local": "0.7.13",
+    "@rudderhq/agent-runtime-utils": "0.7.13",
+    "@rudderhq/db": "0.7.13",
+    "@rudderhq/identity-core": "0.7.13",
+    "@rudderhq/run-intelligence-core": "0.7.13",
+    "@rudderhq/shared": "0.7.13",
     "ajv": "^8.18.0",
     "ajv-formats": "^3.0.1",
     "better-auth": "1.6.23",

package/resources/bundled-skills/rudder-docs/references/api-reference.md

@@ -138,6 +138,8 @@ Use the incremental `after` form when you already know the thread.
 - `GET /api/orgs/:orgId/issues`
 - `POST /api/orgs/:orgId/issues`
 - `GET /api/orgs/:orgId/agents`
+- `GET /api/orgs/:orgId/members/directory`
+  - Returns `total/items/nextCursor/hasMore` with `Name`, `Type`, `Role`, and `Ref`; use `fullIds=true` only for explicit UUID debugging.
 - `POST /api/orgs/:orgId/agent-hires`
 - `GET /api/orgs/:orgId/dashboard`
 - `GET /api/orgs/:orgId/projects`
@@ -158,6 +160,12 @@ in `pending_approval` plus the approval record when organization policy requires
 review. Normal runtime work should follow [Agent creation](agent-creation.md)
 and the installed CLI instead of calling this route directly.
 
+The member directory is a read-only, organization-scoped view for Agent
+context. It returns only active visible members with `name`, `type`, `role`,
+and typed short `ref` fields. Agent keys may read their own organization;
+cross-organization requests are rejected. Use `query`, `type`, `limit`, and
+`cursor` for bounded pagination.
+
 ### Resources
 
 - `GET /api/orgs/:orgId/resources`

package/resources/bundled-skills/rudder-docs/references/cli-reference.md

@@ -32,14 +32,14 @@ operating-practices guide for operating behavior:
 
 - First-party MCP tools use the stable `rudder_<capability_id>` naming convention, for example `rudder_issue_checkout` for `issue.checkout`.
 - All commands support `--json`.
-- CLI output renders IDs as short IDs by default; `rudder runs ...` commands accept short run IDs. Add `--full-ids` only when a debugging or compatibility workflow needs raw UUIDs.
+- CLI output renders IDs as typed short IDs by default (`agt_`, `cht_`, `run_`, `msg_`, `cmt_`, and related refs); `rudder runs ...` commands accept typed refs, legacy bare short run IDs, or full UUIDs. Add `--full-ids` only when a debugging or compatibility workflow needs raw UUIDs.
 - `--org-id` defaults to `RUDDER_ORG_ID` when relevant.
 - `--run-id` defaults to `RUDDER_RUN_ID` and is attached to mutating requests when available.
 - `issue checkout` defaults `--agent-id` from `RUDDER_AGENT_ID`.
 
 ## JSON Output Contract
 
-`rudder ... --json` commands must write valid JSON to stdout on success. ID fields in CLI JSON use short display IDs by default; pass `--full-ids` to preserve raw UUIDs. Short run IDs returned by CLI output can be passed back into `rudder runs get`, `events`, `log`, `transcript`, `errors`, `cancel`, and `retry`. If a command cannot produce the requested JSON, it must exit nonzero and write a diagnostic error to stderr. An exit-0 command with empty stdout is a CLI/runtime defect, not a valid empty result.
+`rudder ... --json` commands must write valid JSON to stdout on success. ID fields in CLI JSON use typed short display IDs by default; pass `--full-ids` to preserve raw UUIDs. Typed or legacy short run IDs returned by CLI output can be passed back into `rudder runs get`, `events`, `log`, `transcript`, `errors`, `cancel`, and `retry`. If a command cannot produce the requested JSON, it must exit nonzero and write a diagnostic error to stderr. An exit-0 command with empty stdout is a CLI/runtime defect, not a valid empty result.
 
 ## Agent V1 Commands
 
@@ -47,6 +47,7 @@ operating-practices guide for operating behavior:
 | --- | --- | --- | --- | --- | --- | --- |
 | `rudder_agent_me` | `rudder agent me` | Show the authenticated agent identity and budget. | no | no | no | no |
 | `rudder_agent_inbox` | `rudder agent inbox` | List the compact assignee and reviewer work inbox for the authenticated agent. | no | no | no | no |
+| `rudder_organization_members_list` | `rudder org members --org-id <id> [--query <text>] [--type <human|agent|all>] [--limit <n>] [--cursor <cursor>]` | List active visible human and agent members in the authenticated organization. | no | required | no | no |
 | `rudder_agent_capabilities` | `rudder agent capabilities` | List the stable Rudder agent command contract. | no | no | no | no |
 | `rudder_agent_update` | `rudder agent update [agent-id] [--title <title>] [--description <text>]` | Update an agent's identity fields; defaults to the authenticated agent. | yes | no | no | attached when available |
 | `rudder_agent_skills_create` | `rudder agent skills create [agent-id] --name <name> [--enable]` | Create an agent-private skill package under AGENT_HOME/skills. | yes | no | no | attached when available |
@@ -81,6 +82,7 @@ operating-practices guide for operating behavior:
 | `rudder_library_file_ref` | `rudder library file ref <path>` | Return the stable Markdown reference for one Library file without printing file content. | no | required | no | no |
 | `rudder_library_file_link` | `rudder library file link <path>` | Compatibility alias for `rudder library file ref <path>`. | no | required | no | no |
 | `rudder_library_file_put` | `rudder library file put <path> --body-file <path>` | Fallback create/update when local filesystem access is unavailable; JSON includes `mentionHref` and `markdownLink`. | yes | required | no | attached when available |
+| `rudder_issue_create` | `rudder issue create --org-id <id> ... [--label-id <id> ...] [--label <name> ...]` | Create a new issue or subtask with the generic issue surface; agent-created issues default to the creating agent when no assignee is supplied. | yes | required | no | attached when available |
 | `rudder_approval_get` | `rudder approval get <approval-id>` | Read one approval request. | no | no | no | no |
 | `rudder_approval_issues` | `rudder approval issues <approval-id>` | List the issues linked to an approval. | no | no | no | no |
 | `rudder_approval_comment` | `rudder approval comment <approval-id> --body-file <path>` | Add a comment to an approval. | yes | no | no | attached when available |
@@ -161,6 +163,8 @@ Issue comment responses include `shortRef` when available. `rudder issue comment
 
 Chat conversation responses include `shortRef` when available. Chat read and mutation commands accept the organization-scoped `cht_<uuid-prefix>` value or the full conversation UUID. Human-readable `chat list` and `chat search` output prefers `shortRef`; `--json` retains both `id` and `shortRef`, and `--full-ids` preserves the durable UUID value in `id`. Use the full UUID when a short ref is ambiguous.
 
+Agent run and message responses include typed `shortRef` values when available. Agent-facing output prefers `run_<uuid-prefix>` and `msg_<uuid-prefix>` while preserving the durable UUID in `id`; `--full-ids` restores the UUID values. Run routes accept `run_` refs, legacy bare hex prefixes, and full UUIDs within the authorized organization scope. Ambiguous prefixes return `409` with typed candidates.
+
 `--image` may be repeated. The CLI uploads each local PNG/JPEG/WebP/GIF as an issue attachment and appends Markdown image links to the comment text before sending it.
 
 ## Renderable Library CLI Output
@@ -194,7 +198,6 @@ Reviewer policy lives in [Review and close-out](operating-practices.md#review-an
 - `rudder agent config list --org-id <id>` — List redacted agent configuration snapshots for an organization.
 - `rudder agent config get <agent-id-or-shortname>` — Read one redacted agent configuration snapshot by id or shortname.
 - `rudder agent icons` — List legacy named agent icons for compatibility/debugging; normal create and hire payloads should omit icon.
-- `rudder issue create --org-id <id> ... [--label-id <id> ...] [--label <name> ...]` — Create a new issue or subtask with the generic issue surface; agent-created issues default to the creating agent when no assignee is supplied.
 - `rudder issue labels list --org-id <id>` — List organization issue labels available for issue creation.
 - `rudder approval create --org-id <id> --type <type> --payload <json>` — Create a new approval request.
 - `rudder approval resubmit <approval-id> [--payload <json>]` — Resubmit a revision-requested approval, optionally with updated payload.

package/skills/rudder-docs/references/api-reference.md

@@ -138,6 +138,8 @@ Use the incremental `after` form when you already know the thread.
 - `GET /api/orgs/:orgId/issues`
 - `POST /api/orgs/:orgId/issues`
 - `GET /api/orgs/:orgId/agents`
+- `GET /api/orgs/:orgId/members/directory`
+  - Returns `total/items/nextCursor/hasMore` with `Name`, `Type`, `Role`, and `Ref`; use `fullIds=true` only for explicit UUID debugging.
 - `POST /api/orgs/:orgId/agent-hires`
 - `GET /api/orgs/:orgId/dashboard`
 - `GET /api/orgs/:orgId/projects`
@@ -158,6 +160,12 @@ in `pending_approval` plus the approval record when organization policy requires
 review. Normal runtime work should follow [Agent creation](agent-creation.md)
 and the installed CLI instead of calling this route directly.
 
+The member directory is a read-only, organization-scoped view for Agent
+context. It returns only active visible members with `name`, `type`, `role`,
+and typed short `ref` fields. Agent keys may read their own organization;
+cross-organization requests are rejected. Use `query`, `type`, `limit`, and
+`cursor` for bounded pagination.
+
 ### Resources
 
 - `GET /api/orgs/:orgId/resources`

package/skills/rudder-docs/references/cli-reference.md

@@ -32,14 +32,14 @@ operating-practices guide for operating behavior:
 
 - First-party MCP tools use the stable `rudder_<capability_id>` naming convention, for example `rudder_issue_checkout` for `issue.checkout`.
 - All commands support `--json`.
-- CLI output renders IDs as short IDs by default; `rudder runs ...` commands accept short run IDs. Add `--full-ids` only when a debugging or compatibility workflow needs raw UUIDs.
+- CLI output renders IDs as typed short IDs by default (`agt_`, `cht_`, `run_`, `msg_`, `cmt_`, and related refs); `rudder runs ...` commands accept typed refs, legacy bare short run IDs, or full UUIDs. Add `--full-ids` only when a debugging or compatibility workflow needs raw UUIDs.
 - `--org-id` defaults to `RUDDER_ORG_ID` when relevant.
 - `--run-id` defaults to `RUDDER_RUN_ID` and is attached to mutating requests when available.
 - `issue checkout` defaults `--agent-id` from `RUDDER_AGENT_ID`.
 
 ## JSON Output Contract
 
-`rudder ... --json` commands must write valid JSON to stdout on success. ID fields in CLI JSON use short display IDs by default; pass `--full-ids` to preserve raw UUIDs. Short run IDs returned by CLI output can be passed back into `rudder runs get`, `events`, `log`, `transcript`, `errors`, `cancel`, and `retry`. If a command cannot produce the requested JSON, it must exit nonzero and write a diagnostic error to stderr. An exit-0 command with empty stdout is a CLI/runtime defect, not a valid empty result.
+`rudder ... --json` commands must write valid JSON to stdout on success. ID fields in CLI JSON use typed short display IDs by default; pass `--full-ids` to preserve raw UUIDs. Typed or legacy short run IDs returned by CLI output can be passed back into `rudder runs get`, `events`, `log`, `transcript`, `errors`, `cancel`, and `retry`. If a command cannot produce the requested JSON, it must exit nonzero and write a diagnostic error to stderr. An exit-0 command with empty stdout is a CLI/runtime defect, not a valid empty result.
 
 ## Agent V1 Commands
 
@@ -47,6 +47,7 @@ operating-practices guide for operating behavior:
 | --- | --- | --- | --- | --- | --- | --- |
 | `rudder_agent_me` | `rudder agent me` | Show the authenticated agent identity and budget. | no | no | no | no |
 | `rudder_agent_inbox` | `rudder agent inbox` | List the compact assignee and reviewer work inbox for the authenticated agent. | no | no | no | no |
+| `rudder_organization_members_list` | `rudder org members --org-id <id> [--query <text>] [--type <human|agent|all>] [--limit <n>] [--cursor <cursor>]` | List active visible human and agent members in the authenticated organization. | no | required | no | no |
 | `rudder_agent_capabilities` | `rudder agent capabilities` | List the stable Rudder agent command contract. | no | no | no | no |
 | `rudder_agent_update` | `rudder agent update [agent-id] [--title <title>] [--description <text>]` | Update an agent's identity fields; defaults to the authenticated agent. | yes | no | no | attached when available |
 | `rudder_agent_skills_create` | `rudder agent skills create [agent-id] --name <name> [--enable]` | Create an agent-private skill package under AGENT_HOME/skills. | yes | no | no | attached when available |
@@ -81,6 +82,7 @@ operating-practices guide for operating behavior:
 | `rudder_library_file_ref` | `rudder library file ref <path>` | Return the stable Markdown reference for one Library file without printing file content. | no | required | no | no |
 | `rudder_library_file_link` | `rudder library file link <path>` | Compatibility alias for `rudder library file ref <path>`. | no | required | no | no |
 | `rudder_library_file_put` | `rudder library file put <path> --body-file <path>` | Fallback create/update when local filesystem access is unavailable; JSON includes `mentionHref` and `markdownLink`. | yes | required | no | attached when available |
+| `rudder_issue_create` | `rudder issue create --org-id <id> ... [--label-id <id> ...] [--label <name> ...]` | Create a new issue or subtask with the generic issue surface; agent-created issues default to the creating agent when no assignee is supplied. | yes | required | no | attached when available |
 | `rudder_approval_get` | `rudder approval get <approval-id>` | Read one approval request. | no | no | no | no |
 | `rudder_approval_issues` | `rudder approval issues <approval-id>` | List the issues linked to an approval. | no | no | no | no |
 | `rudder_approval_comment` | `rudder approval comment <approval-id> --body-file <path>` | Add a comment to an approval. | yes | no | no | attached when available |
@@ -161,6 +163,8 @@ Issue comment responses include `shortRef` when available. `rudder issue comment
 
 Chat conversation responses include `shortRef` when available. Chat read and mutation commands accept the organization-scoped `cht_<uuid-prefix>` value or the full conversation UUID. Human-readable `chat list` and `chat search` output prefers `shortRef`; `--json` retains both `id` and `shortRef`, and `--full-ids` preserves the durable UUID value in `id`. Use the full UUID when a short ref is ambiguous.
 
+Agent run and message responses include typed `shortRef` values when available. Agent-facing output prefers `run_<uuid-prefix>` and `msg_<uuid-prefix>` while preserving the durable UUID in `id`; `--full-ids` restores the UUID values. Run routes accept `run_` refs, legacy bare hex prefixes, and full UUIDs within the authorized organization scope. Ambiguous prefixes return `409` with typed candidates.
+
 `--image` may be repeated. The CLI uploads each local PNG/JPEG/WebP/GIF as an issue attachment and appends Markdown image links to the comment text before sending it.
 
 ## Renderable Library CLI Output
@@ -194,7 +198,6 @@ Reviewer policy lives in [Review and close-out](operating-practices.md#review-an
 - `rudder agent config list --org-id <id>` — List redacted agent configuration snapshots for an organization.
 - `rudder agent config get <agent-id-or-shortname>` — Read one redacted agent configuration snapshot by id or shortname.
 - `rudder agent icons` — List legacy named agent icons for compatibility/debugging; normal create and hire payloads should omit icon.
-- `rudder issue create --org-id <id> ... [--label-id <id> ...] [--label <name> ...]` — Create a new issue or subtask with the generic issue surface; agent-created issues default to the creating agent when no assignee is supplied.
 - `rudder issue labels list --org-id <id>` — List organization issue labels available for issue creation.
 - `rudder approval create --org-id <id> --type <type> --payload <json>` — Create a new approval request.
 - `rudder approval resubmit <approval-id> [--payload <json>]` — Resubmit a revision-requested approval, optionally with updated payload.