insta 0.0.62 → 0.0.63

package/README.md

@@ -121,10 +121,15 @@ only. Provider-minted service credentials (`DATABASE_URL`, `BUCKET_NAME`,
 
 ### Destructive actions can require approval
 
-Reading secrets, deploying, deleting a project or branch, and changing services are
-governed by a per-project policy. Where the policy says `approve`, the command stops and
-prints an approval id for an admin to grant with `insta approvals approve <id>`. Run
-`insta policy get` for the live policy.
+Agent requests are governed by the project's `agent-policy`; human requests use normal RBAC.
+Where the agent policy says `approve`, the command stops and prints an approval id for a human
+admin to grant with `insta approvals approve <id>`. The agent then retries the unchanged request.
+Run `insta --agent agent-policy get --json` for stored overrides, `defaultRules`, `effectiveRules`,
+`bootstrapRules` and `ruleNotes`. Rules distinguish no affected branches (`project`), unprotected
+branches and protected branches. They describe policy, not authorization: RBAC, session checks,
+actual affected resources and compound actions still apply. An empty override object does not
+mean rules are unavailable. Text output also lists effective rules. The old `policy` command and approval
+`--always` option have been removed.
 
 ### Agents get the same surface
 
@@ -213,7 +218,7 @@ build never reaches a production installer.
 | `insta metrics` · `logs` · `events` | Service metrics; runtime logs (`--deploy` for deploy events); audit timeline |
 | `insta usage` · `billing` | Usage by billing dimension; `billing upgrade` · `billing portal` |
 | `insta approvals` | `list` · `approve` · `deny` |
-| `insta policy` | `get` · `set <action> <decision>` |
+| `insta agent-policy` | `get` · `set <mode>` · `protect-branch` · `unprotect-branch` · `rule set <action> <decision>` · `revoke-sessions` |
 | `insta observe` | `install` · `uninstall` · `report` · `sync` — local credential audit |
 | `insta feedback` | Report an InstaCloud-side hurdle (bug / feature-request / friction) to the team — never for the app you are building; works logged-out |
 | `insta upgrade` · `autoupdate` | Update the CLI; show or set auto-update |

package/dist/agent.js

@@ -0,0 +1,86 @@
+import { createHash, generateKeyPairSync, randomUUID, sign } from 'node:crypto';
+import { chmod, mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { findProjectRoot, readProject } from './config.js';
+import { alreadyTracked, ensureGitignore } from './gitignore.js';
+let mode = null;
+export function detectAgent(explicit, env = process.env) {
+    const client = env.CODEX_THREAD_ID || env.CODEX_CI === '1' ? 'codex'
+        : env.CLAUDECODE === '1' ? 'claude-code'
+            : env.CURSOR_AGENT === '1' ? 'cursor' : 'unknown';
+    return explicit || client !== 'unknown' ? { source: explicit ? 'cli-explicit' : 'cli-detected', client } : null;
+}
+export function configureAgent(value) { mode = value; }
+export function agentMode() { return mode; }
+const hash = (v) => createHash('sha256').update(v).digest('hex');
+export function canonicalTarget(path) {
+    const url = new URL(path, 'https://platform.invalid');
+    return url.pathname + url.search;
+}
+const guidance = 'agent session missing, expired, or for another project/environment — run `insta setup agent`';
+export async function issueAgentSession(api, projectId) {
+    const pair = generateKeyPairSync('ed25519');
+    const client = mode?.client ?? detectAgent(false)?.client ?? 'unknown';
+    const out = await api.request('POST', '/agent/sessions', {
+        projectId, client, publicKey: pair.publicKey.export({ type: 'spki', format: 'pem' }).toString(),
+    });
+    return { ...out, client, apiUrl: api.apiUrl.replace(/\/+$/, ''), privateKey: pair.privateKey.export({ type: 'pkcs8', format: 'pem' }).toString() };
+}
+export async function saveAgentSession(session, cwd = process.cwd()) {
+    const root = await findProjectRoot(cwd) ?? cwd;
+    const rel = '.insta/agent-session.json';
+    if (alreadyTracked(root, [rel]).length)
+        throw new Error('agent-session.json is tracked by Git; untrack it before running insta setup agent');
+    ensureGitignore(root, [rel], '# Local agent credentials');
+    const dir = join(root, '.insta');
+    await mkdir(dir, { recursive: true });
+    const temp = join(dir, `.agent-session-${randomUUID()}.tmp`);
+    // Ignore crash leftovers too; temporary files contain the same private material.
+    ensureGitignore(root, ['.insta/.agent-session-*.tmp']);
+    await writeFile(temp, JSON.stringify(session, null, 2), { mode: 0o600 });
+    await rename(temp, join(root, rel));
+    await chmod(join(root, rel), 0o600);
+}
+export async function setupProjectAgentSession(api, projectId) {
+    const id = projectId ?? (await readProject())?.projectId;
+    if (!id)
+        return false;
+    await saveAgentSession(await issueAgentSession(api, id));
+    return true;
+}
+export async function loadAgentSession(apiUrl, projectId, cwd = process.cwd()) {
+    try {
+        const root = await findProjectRoot(cwd) ?? cwd;
+        const session = JSON.parse(await readFile(join(root, '.insta/agent-session.json'), 'utf8'));
+        if (session.projectId !== projectId || session.apiUrl !== apiUrl.replace(/\/+$/, '') || !session.token || !session.privateKey
+            || !Number.isFinite(Date.parse(session.expiresAt)) || Date.parse(session.expiresAt) <= Date.now())
+            throw new Error();
+        return session;
+    }
+    catch {
+        throw new Error(guidance);
+    }
+}
+export async function agentHeaders(api, method, path, rawBody) {
+    if (!mode)
+        return {};
+    if (canonicalTarget(path) === '/agent/sessions' && method === 'POST')
+        return {
+            'Insta-Actor-Type': 'agent', 'Insta-Agent-Source': mode.source, 'Insta-Agent-Client': mode.client,
+        };
+    const target = canonicalTarget(path);
+    const match = target.match(/^\/projects\/([^/?]+)/);
+    // Account reads/project creation have no project policy yet. Mint a short-lived bootstrap
+    // assertion in memory. It cannot access project routes; never downgrade to a human request.
+    const session = match ? await loadAgentSession(api.apiUrl, decodeURIComponent(match[1])) : await issueAgentSession(api);
+    const timestamp = String(Math.floor(Date.now() / 1000));
+    const nonce = randomUUID();
+    const proof = [method.toUpperCase(), target, hash(rawBody), session.agentSessionId, timestamp, nonce, mode.source, session.client].join('\n');
+    return {
+        'Insta-Actor-Type': 'agent', 'Insta-Agent-Session': session.agentSessionId,
+        'Insta-Agent-Session-Token': session.token, 'Insta-Agent-Source': mode.source,
+        'Insta-Agent-Client': session.client, 'Insta-Agent-Timestamp': timestamp,
+        'Insta-Agent-Nonce': nonce, 'Insta-Agent-Signature': sign(null, Buffer.from(proof), session.privateKey).toString('base64url'),
+    };
+}
+//# sourceMappingURL=agent.js.map

package/dist/api.js

@@ -4,6 +4,7 @@ import { readGlobal, writeGlobal, readProject, writeProject } from './config.js'
 import { autoResolveProject, promptChoice } from './resolve-project.js';
 import { die } from './util.js';
 import { USER_AGENT } from './version.js';
+import { agentHeaders, agentMode } from './agent.js';
 export class ApiError extends Error {
     status;
     body;
@@ -16,6 +17,13 @@ export class ApiError extends Error {
         this.name = 'ApiError';
     }
 }
+export class AgentApprovalRequired extends Error {
+    body;
+    constructor(body) {
+        super(body.message ?? `approval required: ${body.approvalId}`);
+        this.body = body;
+    }
+}
 // Store a durable insta_ key as the credential: set it as the bearer and drop any refresh token (an insta_ key never rotates; a stale one would leak to /auth/refresh on a 401).
 export function storeApiKeyCredential(cfg, token, user) {
     cfg.accessToken = token;
@@ -53,6 +61,8 @@ export class ApiClient {
     // Returns parsed body for status < 400 (incl. 202); throws ApiError otherwise.
     async request(method, path, body, opts = {}) {
         const res = await this.raw(method, path, body, opts.auth ?? true);
+        if (agentMode() && res.status === 202 && res.body?.status === 'approval_required')
+            throw new AgentApprovalRequired(res.body);
         if (res.status >= 400)
             throw new ApiError(res.status, res.body?.error ?? `HTTP ${res.status}`, res.body);
         return res.body;
@@ -76,6 +86,8 @@ export class ApiClient {
         const headers = { 'Content-Type': 'application/json', 'Insta-Hints': '1', 'User-Agent': USER_AGENT };
         if (auth && this.cfg.accessToken)
             headers.Authorization = `Bearer ${this.cfg.accessToken}`;
+        if (auth)
+            Object.assign(headers, await agentHeaders(this, method, path, body === undefined ? '' : JSON.stringify(body)));
         const res = await this.fetchImpl(this.apiUrl + path, {
             method,
             headers,
@@ -113,6 +125,8 @@ export async function requireProject() {
     const p = await readProject();
     if (p)
         return p;
+    if (agentMode())
+        die('agent mode requires a linked project — run `insta setup agent --project <id>`');
     // One command, just works: unlinked ≠ error. Resolve the project (auto when there's one,
     // one-keystroke picker when several) and persist the choice so this happens once per dir.
     const api = await ApiClient.load();

package/dist/commands/agent-policy.js

@@ -0,0 +1,72 @@
+import { ApiClient, requireProject } from '../api.js';
+import { handleApproval, info, printJson } from '../util.js';
+async function current() {
+    const api = await ApiClient.load();
+    const project = await requireProject();
+    const path = `/projects/${project.projectId}/agent-policy`;
+    const out = await api.request('GET', path);
+    return { api, project, path, policy: out.policy, out };
+}
+export function displayPolicy(out, opts, output = { info, printJson }) {
+    const { info, printJson } = output;
+    const { policy, agentSessionEpoch } = out;
+    if (opts.json)
+        return printJson(out);
+    info(`agent policy: ${policy.mode}\nprotected branches: ${policy.protectedBranchIds.join(', ') || '(none)'}\nsession epoch: ${agentSessionEpoch}`);
+    if (out.effectiveRules) {
+        for (const [scope, rules] of Object.entries(out.effectiveRules)) {
+            info(`\n${scope}:`);
+            for (const [action, decision] of Object.entries(rules))
+                info(`  ${action}: ${decision}`);
+        }
+        info(`\nbootstrap: project.create = ${out.bootstrapRules?.['project.create'] ?? '(not reported)'}`);
+        for (const note of out.ruleNotes ?? [])
+            info(note);
+    }
+    else
+        info('This Platform does not expose resolved rules; upgrade Platform to inspect defaults.');
+}
+export async function get(opts) {
+    const { out } = await current();
+    // Forward the public response, never the internal API client (which holds credentials).
+    displayPolicy(out, opts);
+}
+async function update(change, opts) {
+    const state = await current();
+    await change(state.policy, state);
+    const result = await state.api.rawRequest('PUT', state.path, state.policy);
+    if (handleApproval(result, opts.json))
+        return;
+    if (opts.json)
+        return printJson(result.body);
+    info(`agent policy updated: ${result.body.policy.mode}`);
+}
+export async function set(mode, opts) {
+    const normalized = mode.replace(/-/g, '_');
+    if (!['full_access', 'read_only', 'branch_developer'].includes(normalized))
+        throw new Error('mode must be full-access, read-only, or branch-developer');
+    return update(policy => { policy.mode = normalized; }, opts);
+}
+export async function protect(branch, enabled, opts) {
+    return update(async (policy, { api, project }) => {
+        const { branches } = await api.request('GET', `/projects/${project.projectId}/branches`);
+        const found = branches.find((b) => b.id === branch || b.name === branch);
+        if (!found)
+            throw new Error('branch not found');
+        policy.protectedBranchIds = enabled ? [...new Set([...policy.protectedBranchIds, found.id])] : policy.protectedBranchIds.filter((id) => id !== found.id);
+    }, opts);
+}
+export async function rule(action, decision, opts) {
+    if (!['allow', 'deny', 'approve'].includes(decision))
+        throw new Error('decision must be allow, deny, or approve');
+    return update(policy => { policy.branchDeveloperRules[action] = decision; }, opts);
+}
+export async function revoke(opts) {
+    const api = await ApiClient.load();
+    const project = await requireProject();
+    const out = await api.request('POST', `/projects/${project.projectId}/agent-sessions/revoke`);
+    if (opts.json)
+        return printJson(out);
+    info(`all project agent sessions revoked (epoch ${out.agentSessionEpoch})`);
+}
+//# sourceMappingURL=agent-policy.js.map

package/dist/commands/compute.js

@@ -429,6 +429,8 @@ function operandIndices(argv, from, to = argv.length) {
 function execCommandIndex(argv) {
     for (let cursor = 2; cursor < argv.length; cursor++) {
         const token = argv[cursor];
+        if (token === '--agent')
+            continue;
         if (token.startsWith('-'))
             return -1; // a global flag, or `--`: either way not our command path
         return token === 'compute' && argv[cursor + 1] === 'exec' ? cursor : -1;

package/dist/commands/govern.js

@@ -28,10 +28,10 @@ export async function approvalsList(opts) {
 export async function approvalsApprove(id, opts) {
     const api = await ApiClient.load();
     const p = await requireProject();
-    const out = await api.request('POST', `/projects/${p.projectId}/approvals/${id}/approve`, { always: !!opts.always });
+    const out = await api.request('POST', `/projects/${p.projectId}/approvals/${id}/approve`, {});
     if (opts.json)
         return printJson(out);
-    info(`approved ${out.approval.action} (${id})${opts.always ? ' — policy set to allow' : ''}`);
+    info(`approved ${out.approval.action} (${id})`);
 }
 export async function approvalsDeny(id, opts = {}) {
     const api = await ApiClient.load();
@@ -41,21 +41,4 @@ export async function approvalsDeny(id, opts = {}) {
         return printJson(out);
     info(`denied ${out.approval.action} (${id})`);
 }
-export async function policyGet(opts) {
-    const api = await ApiClient.load();
-    const p = await requireProject();
-    const { policy } = await api.request('GET', `/projects/${p.projectId}/policy`);
-    if (opts.json)
-        return printJson(policy);
-    for (const [action, decision] of Object.entries(policy))
-        info(`${action}: ${decision}`);
-}
-export async function policySet(action, decision, opts = {}) {
-    const api = await ApiClient.load();
-    const p = await requireProject();
-    const out = await api.request('PUT', `/projects/${p.projectId}/policy/${action}`, { decision });
-    if (opts.json)
-        return printJson({ action, decision, ...(out ?? {}) });
-    info(`policy ${action} = ${decision}`);
-}
 //# sourceMappingURL=govern.js.map

package/dist/commands/project.js

@@ -1,4 +1,5 @@
 import { homedir } from 'node:os';
+import { agentMode, setupProjectAgentSession } from '../agent.js';
 import { ApiClient, requireProject } from '../api.js';
 import { writeProject } from '../config.js';
 import { info, die, printJson, handleApproval, renderNextActions } from '../util.js';
@@ -76,6 +77,8 @@ export async function projectCreate(name, opts) {
     const orgId = await resolveOrg(api, opts.org);
     const out = await api.request('POST', `/orgs/${orgId}/projects`, { name: resolved });
     await writeProject({ projectId: out.project.id, orgId, branch: out.defaultBranch.name });
+    if (agentMode())
+        await setupProjectAgentSession(api, out.project.id);
     if (opts.json) {
         printJson({ ...out, linked: { projectId: out.project.id, orgId, branch: out.defaultBranch.name } });
     }
@@ -101,6 +104,8 @@ export async function projectList(opts) {
 }
 export async function projectLink(id, opts = {}) {
     const api = await ApiClient.load();
+    if (agentMode())
+        await setupProjectAgentSession(api, id);
     const { project } = await api.request('GET', `/projects/${id}`);
     await writeProject({ projectId: project.id, orgId: project.org_id, branch: 'main' });
     if (opts.json)

package/dist/commands/setup.js

@@ -11,6 +11,7 @@ import { join } from 'node:path';
 import os from 'node:os';
 import { createInterface } from 'node:readline';
 import { ApiClient } from '../api.js';
+import { setupProjectAgentSession } from '../agent.js';
 import { readPersistedGlobal, resolveEnv } from '../config.js';
 import { DEFAULT_ENV, ENVS, ENV_NAMES, envForApiUrl, envFromEnvVar, isEnvName, mcpServerName } from '../env.js';
 import { info, openUrl } from '../util.js';
@@ -362,7 +363,7 @@ export async function setupAgent(opts, run = defaultRunner, mint, installConfigs
     login: () => loginDevice({}, openUrl),
     stdinTty: canPromptViaTty(),
     stdoutTty: !!process.stdout.isTTY,
-}, link = projectLink, create = (n) => projectCreate(n, {})) {
+}, link = projectLink, create = (n) => projectCreate(n, {}), enroll = async () => setupProjectAgentSession(await ApiClient.load())) {
     if (!opts.yes && !process.stdout.isTTY) {
         info('non-interactive shell — assuming -y');
     }
@@ -457,6 +458,13 @@ export async function setupAgent(opts, run = defaultRunner, mint, installConfigs
             }
         }
     }
+    if (loggedIn) {
+        if (await enroll())
+            info('✓ Project agent session ready (expires in 24 hours; refresh with insta setup agent)');
+    }
+    else {
+        info('  project agent session not created — run `insta login`, then `insta setup agent`');
+    }
     // THE summary line. The restart note exists because config-file agents only read their MCP
     // config at startup; the skill files need no restart.
     const mcpOk = claude === 'new' || claude === 'existing' || others.length > 0;

package/dist/config.js

@@ -2,6 +2,7 @@
 import { homedir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
 import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { ensureGitignore } from './gitignore.js';
 import { DEFAULT_ENV, ENVS, envForApiUrl, envFromEnvVar, normalizeUrl } from './env.js';
 const GLOBAL_DIR = join(homedir(), '.insta');
 const GLOBAL_FILE = join(GLOBAL_DIR, 'config.json');
@@ -125,6 +126,7 @@ export async function readProject(cwd = process.cwd()) {
 export async function writeProject(c, cwd = process.cwd()) {
     const target = (await findProjectRoot(cwd)) ?? cwd;
     await mkdir(join(target, PROJECT_DIR), { recursive: true });
+    ensureGitignore(target, ['.insta/agent-session.json'], '# Local agent credentials');
     await writeFile(join(target, PROJECT_DIR, PROJECT_FILE), JSON.stringify(c, null, 2));
 }
 //# sourceMappingURL=config.js.map

package/dist/index.js

@@ -1,6 +1,8 @@
 #!/usr/bin/env node
 import { Command } from 'commander';
-import { ApiError } from './api.js';
+import { configureAgent, detectAgent } from './agent.js';
+import * as agentPolicy from './commands/agent-policy.js';
+import { ApiError, AgentApprovalRequired } from './api.js';
 import { CliCancel, CliExit, fail, relayedExitCode } from './util.js';
 import { trackCommand } from './telemetry.js';
 import { cliVersion } from './version.js';
@@ -32,6 +34,14 @@ import { billing, billingUpgrade, billingPortal } from './commands/billing.js';
 import * as selfUpdate from './commands/upgrade.js';
 import * as feedbackCmd from './commands/feedback.js';
 function onError(e) {
+    if (e instanceof AgentApprovalRequired) {
+        if (process.argv.includes('--json'))
+            process.stdout.write(JSON.stringify(e.body) + '\n');
+        else
+            process.stderr.write(e.message + '\n');
+        process.exitCode = 2;
+        return;
+    }
     if (e instanceof CliExit || e instanceof CliCancel)
         return;
     if (e instanceof ApiError)
@@ -64,6 +74,8 @@ const program = new Command();
 // against the subcommand's own (identically-named) option instead.
 program.enablePositionalOptions();
 program.name('insta').description('InstaCloud CLI — manage projects, branches, secrets, deploys').version(cliVersion());
+program.option('--agent', 'run as an agent with a verified project session and project agent policy');
+program.hook('preAction', () => configureAgent(detectAgent(!!program.opts().agent)));
 // ---- auth ----
 program.command('login').description('Log in — bare: sign in from your browser (any account type); or --email <email> + password, --oauth <github|google>, --device (headless), --api-key <insta_…> (headless, durable token)')
     .option('--email <email>', 'account email (email + password login)')
@@ -324,7 +336,7 @@ program.command('events').description('Show the audit + agent-event timeline').o
 // ---- approvals ----
 const ap = program.command('approvals').description('Governance approvals (HITL)');
 ap.command('list').option('--status <s>', 'pending|granted|denied|consumed').option('--json').action(guard((o) => govern.approvalsList(o)));
-ap.command('approve <id>').option('--always', 'also set the policy to allow').option('--json').action(guard((id, o) => govern.approvalsApprove(id, o)));
+ap.command('approve <id>').option('--json').action(guard((id, o) => govern.approvalsApprove(id, o)));
 ap.command('deny <id>').option('--json').action(guard((id, o) => govern.approvalsDeny(id, o)));
 // ---- observe (local credential audit) ----
 const ob = program.command('observe').description('Local credential-audit hook');
@@ -333,9 +345,16 @@ ob.command('uninstall').action(guard(() => observe.observeUninstall()));
 ob.command('report').description('Render the local credential audit').option('--json').action(guard((o) => observe.observeReport(o)));
 ob.command('sync').description('Upload findings into the project timeline').action(guard(() => observe.observeSync()));
 // ---- policy ----
-const pol = program.command('policy').description('Governance policy');
-pol.command('get').option('--json').action(guard((o) => govern.policyGet(o)));
-pol.command('set <action> <decision>').description('action: secrets.read|secrets.write|deploy|project.delete|branch.delete|service.add|service.remove|service.scale|service.upgrade|service.setAccess|storage.read|storage.write|storage.delete; decision: allow|deny|approve').option('--json').action(guard((a, d, o) => govern.policySet(a, d, o)));
+const agentPol = program.command('agent-policy').description('Project agent access policy');
+agentPol.command('get').option('--json').action(guard((o) => agentPolicy.get(o)));
+agentPol.command('set <mode>').description('full-access | read-only | branch-developer')
+    .option('--json').action(guard((mode, o) => agentPolicy.set(mode, o)));
+agentPol.command('protect-branch <branch>').option('--json').action(guard((branch, o) => agentPolicy.protect(branch, true, o)));
+agentPol.command('unprotect-branch <branch>').option('--json').action(guard((branch, o) => agentPolicy.protect(branch, false, o)));
+agentPol.command('rule').command('set <action> <decision>').description('Set an unprotected-branch rule: allow | deny | approve')
+    .option('--json').action(guard((action, decision, o) => agentPolicy.rule(action, decision, o)));
+agentPol.command('revoke-sessions').description('Revoke ALL CLI agent sessions for this project')
+    .option('--json').action(guard((o) => agentPolicy.revoke(o)));
 // ---- feedback (agent + human hurdle reports → the InstaCloud team) ----
 program.command('feedback')
     .description('Report an InstaCloud-side hurdle (bug / missing feature / friction) to the InstaCloud team — about the insta toolkit itself, NEVER about the app you are building. Works logged-out and unlinked.')

package/dist/telemetry.js

@@ -39,7 +39,7 @@ const SAFE_ARGS = {
     'compute always-on': { 0: ON_OFF }, 'db always-on': { 0: ON_OFF }, metrics: { 0: TARGET }, logs: { 0: TARGET },
     'template info': { 0: SLUG }, 'billing upgrade': { 0: oneOf(['pro', 'team']) },
     'approvals approve': { 0: ID }, 'approvals deny': { 0: ID },
-    'policy set': { 0: POLICY_ACTION, 1: oneOf(['allow', 'deny', 'approve']) }, autoupdate: { 0: ON_OFF },
+    'agent-policy rule set': { 0: POLICY_ACTION, 1: oneOf(['allow', 'deny', 'approve']) }, autoupdate: { 0: ON_OFF },
 };
 const SAFE_OPTIONS = {
     org: ID, project: ID, region: REGION, env: ENV, oauth: oneOf(['github', 'google']),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "insta",
-  "version": "0.0.62",
+  "version": "0.0.63",
   "type": "module",
   "description": "InstaCloud CLI — a thin client of the platform control-plane API.",
   "keywords": [