railcode 0.1.25 → 0.1.26

package/README.md

@@ -89,7 +89,13 @@ your saved org and are gated server-side by the same capabilities as the console
     manifest for editing.
   - `railcode agent create --file agent.json` creates an agent; `update <agent>
     --file agent.json` replaces an existing agent manifest; `delete <agent> --yes`
-    archives it.
+    archives it. `--visibility <org|personal>` on `create`/`update`/`test` sets or
+    changes who the agent belongs to (default `org` on create; omitted on `update`
+    leaves it alone). A `personal` agent is invokable and manageable by its
+    creator alone — no grant makes it shared — and `personal -> org` is blocked
+    once created. Requires `agent:create` (personal) or `agent:create_org` (org).
+    `agent show`/`list` print `visibility`, and `show` prints `Owner:` for a
+    personal agent.
   - `railcode agent test --file agent.json --input '{"k":"v"}'` runs a draft
     manifest without saving; `railcode agent run <agent> --input '{"k":"v"}'`
     invokes a saved agent and prints the result. Use `--trace` for the step trace
@@ -97,6 +103,15 @@ your saved org and are gated server-side by the same capabilities as the console
   - `railcode agent schedule set <agent> --cron "0 9 * * *" --timezone UTC`
     creates or updates the agent's one schedule. `schedule show`, `pause`,
     `resume`, `delete --yes`, and `run-now` operate on that single schedule.
+- **`personal-connectors`** (aliases `personal-connector`, `pc`) manages **your
+  own** connected third-party accounts (Gmail, Slack, …), brokered by Composio —
+  distinct from org-admin **service connectors** and from an agent's
+  `tools.personal_connectors`. `list` shows toolkits this deployment brokers and
+  your connection status; `tools <toolkit>` prints that toolkit's callable tools
+  and input schemas; `connect <toolkit>` prints an OAuth URL to open in a
+  browser; `call <toolkit> <tool> [--args '<json>']` runs one tool on your own
+  connected account. Hits the non-org-scoped `/api/personal-connections/*` plane
+  — a personal connection belongs to the human, not the org.
 
 ## Configuration
 

package/dist/index.js

@@ -3809,6 +3809,12 @@ Agent options:
   --input-file <path>                   Read invoke/test input JSON from a file
   --trace                               Include the run step trace in human output
   --yes                                 Confirm delete without a prompt
+  --visibility <org|personal>           create/update/test only (default: org). A personal
+                                         agent is owned/invoked by its creator alone — no
+                                         grant makes it shared, and "personal -> org" is
+                                         blocked once created. Requires the matching
+                                         capability: agent:create for personal,
+                                         agent:create_org for org.
 
 Schedule options:
   --name <name>                         Schedule name (default: default on create)
@@ -3881,9 +3887,10 @@ async function commandAgentList(args) {
         console.log("No managed agents in this organization.");
         return;
     }
-    console.log(formatTable(["name", "model", "uuid", "updated"], agents.map((agent) => [
+    console.log(formatTable(["name", "model", "visibility", "uuid", "updated"], agents.map((agent) => [
         agent.name,
         typeof agent.manifest.model === "string" ? agent.manifest.model : "-",
+        agent.visibility,
         agent.uuid,
         shortDate(agent.updated_at),
     ])));
@@ -3918,13 +3925,14 @@ async function commandAgentPull(args) {
     process.stdout.write(manifest);
 }
 async function commandAgentCreate(args) {
-    assertKnownAgentOptions(args, ["file", "json", "apiUrl"]);
+    assertKnownAgentOptions(args, ["file", "json", "visibility", "apiUrl"]);
     const manifest = readAgentManifest(args);
+    const visibility = agentVisibilityOption(args);
     const config = requireLogin(args);
     const resp = await authedFetch(config, `/api/organizations/${config.orgUuid}/agents`, {
         method: "POST",
         headers: { "Content-Type": "application/json" },
-        body: JSON.stringify({ manifest }),
+        body: JSON.stringify({ manifest, ...(visibility !== undefined ? { visibility } : {}) }),
     });
     if (resp.status === 401)
         await reLoginOrThrow();
@@ -3932,14 +3940,15 @@ async function commandAgentCreate(args) {
     printAgentMutation(result, args.options.json === true, "created");
 }
 async function commandAgentUpdate(args) {
-    assertKnownAgentOptions(args, ["file", "json", "apiUrl"]);
+    assertKnownAgentOptions(args, ["file", "json", "visibility", "apiUrl"]);
     const ref = agentArg(args, "update");
     const manifest = readAgentManifest(args);
+    const visibility = agentVisibilityOption(args);
     const config = requireLogin(args);
     const resp = await authedFetch(config, `/api/organizations/${config.orgUuid}/agents/${encodeURIComponent(ref)}`, {
         method: "PUT",
         headers: { "Content-Type": "application/json" },
-        body: JSON.stringify({ manifest }),
+        body: JSON.stringify({ manifest, ...(visibility !== undefined ? { visibility } : {}) }),
     });
     if (resp.status === 401)
         await reLoginOrThrow();
@@ -3968,14 +3977,15 @@ async function commandAgentDelete(args) {
     console.log(`Agent "${ref}" deleted.`);
 }
 async function commandAgentTest(args) {
-    assertKnownAgentOptions(args, ["file", "input", "inputFile", "json", "trace", "apiUrl"]);
+    assertKnownAgentOptions(args, ["file", "input", "inputFile", "json", "trace", "visibility", "apiUrl"]);
     const manifest = readAgentManifest(args);
     const input = readJsonInput(args);
+    const visibility = agentVisibilityOption(args);
     const config = requireLogin(args);
     const resp = await authedFetch(config, `/api/organizations/${config.orgUuid}/agents/test`, {
         method: "POST",
         headers: { "Content-Type": "application/json" },
-        body: JSON.stringify({ manifest, input }),
+        body: JSON.stringify({ manifest, input, ...(visibility !== undefined ? { visibility } : {}) }),
     });
     if (resp.status === 401)
         await reLoginOrThrow();
@@ -4178,6 +4188,17 @@ function readAgentManifest(args) {
         throw new CliError("Pass --file <agent-manifest.json>.", 2);
     return readJsonObjectFile(path, "Agent manifest");
 }
+// Omitted means "use the server default" on create/test (org) and "leave alone"
+// on update — never send the key unless the caller passed it explicitly.
+function agentVisibilityOption(args) {
+    const value = optionString(args, "visibility");
+    if (value === undefined)
+        return undefined;
+    if (value !== "org" && value !== "personal") {
+        throw new CliError(`Invalid --visibility: ${value} (expected "org" or "personal").`, 2);
+    }
+    return value;
+}
 function readJsonObjectFile(path, label) {
     const resolved = resolve(process.cwd(), path);
     if (!existsSync(resolved))
@@ -4264,6 +4285,7 @@ function printAgentMutation(result, json, verb) {
     }
     console.log(`Agent "${result.agent.name}" ${verb}.`);
     console.log(`UUID: ${result.agent.uuid}`);
+    console.log(`Visibility: ${result.agent.visibility}`);
     if (result.warnings.length > 0) {
         console.log("");
         console.log("Warnings:");
@@ -4276,6 +4298,9 @@ function printAgent(agent) {
     console.log(`UUID: ${agent.uuid}`);
     console.log(`Description: ${agent.description || "-"}`);
     console.log(`Model: ${typeof agent.manifest.model === "string" ? agent.manifest.model : "-"}`);
+    console.log(`Visibility: ${agent.visibility}`);
+    if (agent.visibility === "personal")
+        console.log(`Owner: ${agent.owner_uuid ?? "-"}`);
     console.log(`Updated: ${agent.updated_at}`);
     console.log(`Content hash: ${agent.content_hash}`);
 }
@@ -5124,13 +5149,13 @@ Usage:
   railcode personal-connectors list            Toolkits this deployment brokers + your status
   railcode personal-connectors tools <toolkit> The callable tools of a toolkit (and their inputs)
   railcode personal-connectors connect <toolkit>  Print the OAuth URL to connect it (open in a browser)
-  railcode personal-connectors call <tool> [--args '<json>']  Run one tool on your own account
+  railcode personal-connectors call <toolkit> <tool> [--args '<json>']  Run one tool on your own account
 
 Aliases: personal-connector, pc
 
 Discovery is what you build against: \`tools <toolkit> --json\` shows each tool's
 input schema, so you know what to put in an app's \`personal_connectors:\` and what
-\`personalConnections.call('<tool>', {...})\` expects.
+\`personalConnections.call('<toolkit>', '<tool>', {...})\` expects.
 
 Options:
   --json                                 Print raw JSON instead of a table
@@ -5235,9 +5260,12 @@ async function commandPcConnect(args) {
 }
 async function commandPcCall(args) {
     rejectUnknownOptions(args, ["json", "args", "apiUrl"], "personal-connectors call", PC_HELP);
-    const tool = args.rest[1];
-    if (!tool)
-        throw new CliError("Usage: railcode personal-connectors call <tool> [--args '<json>']", 2);
+    // Scoped by connector: name the toolkit AND the tool.
+    const toolkit = args.rest[1];
+    const tool = args.rest[2];
+    if (!toolkit || !tool) {
+        throw new CliError("Usage: railcode personal-connectors call <toolkit> <tool> [--args '<json>']", 2);
+    }
     let toolArgs = {};
     if (typeof args.options.args === "string") {
         try {
@@ -5251,7 +5279,7 @@ async function commandPcCall(args) {
     const resp = await authedFetch(config, `/api/personal-connections/call`, {
         method: "POST",
         headers: { "Content-Type": "application/json" },
-        body: JSON.stringify({ tool, arguments: toolArgs }),
+        body: JSON.stringify({ toolkit, tool, arguments: toolArgs }),
     });
     if (resp.status === 401)
         await reLoginOrThrow();
@@ -5264,7 +5292,7 @@ async function commandPcCall(args) {
     if (resp.status === 409) {
         throw new CliError(await errorDetail(resp), 1);
     }
-    const body = await readJsonOrThrow(resp, `Call ${tool}`);
+    const body = await readJsonOrThrow(resp, `Call ${toolkit}/${tool}`);
     console.log(JSON.stringify(body, null, 2));
 }
 // ---------------------------------------------------------------------------
@@ -7286,17 +7314,6 @@ async function pcForward(ctx, method, apiPath, body) {
     }
     return { status: upstream.status, body: parsed };
 }
-// Which declared toolkit owns `tool` — asked of the user-plane catalog, scanning
-// only the app's declared toolkits (as the server's app-plane resolver does).
-async function pcResolveToolkit(ctx, entries, tool) {
-    for (const toolkit of pcDeclaredToolkits(entries)) {
-        const { status, body } = await pcForward(ctx, "GET", `/personal-connections/toolkits/${encodeURIComponent(toolkit)}/tools`);
-        if (status === 200 && Array.isArray(body) && body.some((t) => t.slug === tool)) {
-            return toolkit;
-        }
-    }
-    return null;
-}
 const PC_NOT_IN_MANIFEST = (label) => ({
     detail: `personal connector "${label}" was not in the manifest`,
 });
@@ -7336,10 +7353,11 @@ async function handlePersonalConnections(ctx, req, res, path, url) {
         const { status, body } = await pcForward(ctx, "POST", `/personal-connections/${encodeURIComponent(toolkit)}/connect`);
         return sendJson(res, status, body);
     }
-    // call(tool, args) — the load-bearing gate: resolve the tool's toolkit, require
-    // both that toolkit declared AND this specific tool permitted, else 403 (never
-    // forwarded). No declaration at all ⇒ nothing resolves ⇒ refused, matching the
-    // prod chokepoint's "no manifest = refuse".
+    // call(toolkit, tool, args) — the load-bearing gate. Scoped by connector, so
+    // the bound is a direct match against the local manifest: the toolkit must be
+    // declared AND the specific tool permitted, else 403 (never forwarded). No
+    // declaration at all ⇒ refused, matching the prod chokepoint's "no manifest =
+    // refuse". The user plane then verifies the (toolkit, tool) pair is real.
     if (rest === "/call" && req.method === "POST") {
         const raw = await readBody(req);
         let payload;
@@ -7349,16 +7367,15 @@ async function handlePersonalConnections(ctx, req, res, path, url) {
         catch {
             return sendJson(res, 400, { detail: "body must be JSON" });
         }
-        const tool = payload.tool;
-        if (!tool)
-            return sendJson(res, 400, { detail: '"tool" is required' });
-        if (entries.length === 0)
-            return sendJson(res, 403, PC_NOT_IN_MANIFEST(tool));
-        const toolkit = await pcResolveToolkit(ctx, entries, tool);
-        if (!toolkit || !pcAllows(entries, toolkit, tool)) {
-            return sendJson(res, 403, PC_NOT_IN_MANIFEST(tool));
+        const { toolkit, tool } = payload;
+        if (!toolkit || !tool) {
+            return sendJson(res, 400, { detail: '"toolkit" and "tool" are required' });
+        }
+        if (!pcAllows(entries, toolkit, tool)) {
+            return sendJson(res, 403, PC_NOT_IN_MANIFEST(`${toolkit}:${tool}`));
         }
         const { status, body } = await pcForward(ctx, "POST", "/personal-connections/call", {
+            toolkit,
             tool,
             arguments: payload.arguments ?? {},
         });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "railcode",
-  "version": "0.1.25",
+  "version": "0.1.26",
   "description": "Developer CLI for the multi-tenant Railcode platform: log in, scaffold, and deploy static apps.",
   "license": "MIT",
   "type": "module",

package/static/sdk.js

@@ -736,12 +736,12 @@
       () => call("GET", `/personal-connections/${encodeURIComponent(toolkit)}/tools`)
     );
   }
-  function callTool(tool, args = {}) {
+  function callTool(toolkit, tool, args = {}) {
     return track(
       "personalConnections",
-      `personalConnections.call(${q(tool)})`,
+      `personalConnections.call(${q(toolkit)}, ${q(tool)})`,
       () => call("POST", "/personal-connections/call", {
-        body: { tool, arguments: args }
+        body: { toolkit, tool, arguments: args }
       })
     );
   }