feat: add signed agent sessions and governance commands - #182
Open
jwfing wants to merge 1 commit into
Open
Conversation
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
There was a problem hiding this comment.
9 issues found across 9 files
Prompt for AI agents (unresolved issues)
Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.
<file name="src/commands/project.ts">
<violation number="1" location="src/commands/project.ts:102">
P2: In `projectLink`, `setupProjectAgentSession(api, id)` runs before the `GET /projects/{id}` validates the id and before `writeProject` succeeds, so a failed link (typo'd id, no access, network error) still calls `POST /agent/sessions` and writes a signed `.insta/agent-session.json` on disk. `projectCreate` establishes the session only after a successful create+write. Move the call below the GET/link so a failed link doesn't mint/persist agent credentials; it also keeps the two commands' failure behavior consistent.</violation>
</file>
<file name="src/agent.ts">
<violation number="1" location="src/agent.ts:61">
P2: When `.insta/agent-session.json` is partially corrupted or edited, `loadAgentSession` accepts it unless token/privateKey/expiry are also missing. `agentHeaders` then sends an `undefined` session/client value and fails with an opaque server or fetch error instead of the documented `insta setup agent` guidance; validate every field used to build the proof, including `agentSessionId` and `client`, before returning the session.</violation>
</file>
<file name="src/commands/agent-policy.ts">
<violation number="1" location="src/commands/agent-policy.ts:34">
P3: When the platform policy payload lacks `protectedBranchIds`, `protect()` throws on `[...policy.protectedBranchIds, ...]` / `policy.protectedBranchIds.filter(...)`. Default the field to an array before reading it, matching the `get()` output that already treats an empty list as '(none)'.</violation>
<violation number="2" location="src/commands/agent-policy.ts:39">
P3: When the platform policy payload lacks `branchDeveloperRules`, `rule()` throws a TypeError instead of setting the rule. Guard the field before assigning: `policy.branchDeveloperRules ??= {}` so the command works on any policy shape.</violation>
<violation number="3" location="src/commands/agent-policy.ts:44">
P1: When `revoke-sessions` receives HTTP 202 outside agent mode, `request()` returns the approval envelope, so this branch reports success with an undefined epoch (or exits 0 with JSON) without revoking sessions. Use `rawRequest()` and `handleApproval()` before formatting the response, as `update()` does.</violation>
</file>
<file name="src/config.ts">
<violation number="1" location="src/config.ts:147">
P3: This unconditionally creates/updates `.gitignore` (and creates the file if absent) on every project create/link/auto-link, even for human users who never use agent sessions. The agent-session path (saveAgentSession) already adds this exact ignore entry when a session is actually written, so this forces a repository side effect on all non-agent flows. Consider adding the ignore entry only at session-write time.</violation>
</file>
<file name="src/api.ts">
<violation number="1" location="src/api.ts:59">
P3: request()'s docstring and the file-header comment say 202/approval_required returns the parsed body, but the new line throws AgentApprovalRequired for 202 in agent mode. Update the comment to note the 202-throws condition in agent mode so the contract isn't misleading.</violation>
<violation number="2" location="src/api.ts:82">
P2: In agent mode every authenticated non-project API request mints a fresh bootstrap agent session — an ED25519 keypair and a new POST /agent/sessions round-trip — because agentHeaders() calls issueAgentSession() with no caching on each fetch(). This adds keypair generation plus an extra network request to every such API call (and double-mints after a 401 refresh). Cache the bootstrap session after first issuance (or scope session minting to command start) instead of per request.</violation>
</file>
<file name="src/commands/setup.ts">
<violation number="1" location="src/commands/setup.ts:491">
P3: Under agent mode, `insta setup agent --project/--create` enrolls twice: projectLink/projectCreate already call setupProjectAgentSession(api, id) (src/commands/project.ts:78/:102), and then setup.ts calls enroll() again for the same project, issuing a second `/agent/sessions` request/keypair and overwriting the session file. Skip the project-step enrollment when the later enroll() will run, or skip enroll() when the project step already enrolled, to avoid the duplicate issuance.</violation>
</file>
Reply with feedback, questions, or to request a fix.
Re-trigger cubic
| export async function revoke(opts: { json?: boolean }) { | ||
| const api = await ApiClient.load() | ||
| const project = await requireProject() | ||
| const out = await api.request('POST', `/projects/${project.projectId}/agent-sessions/revoke`) |
There was a problem hiding this comment.
P1: When revoke-sessions receives HTTP 202 outside agent mode, request() returns the approval envelope, so this branch reports success with an undefined epoch (or exits 0 with JSON) without revoking sessions. Use rawRequest() and handleApproval() before formatting the response, as update() does.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At src/commands/agent-policy.ts, line 44:
<comment>When `revoke-sessions` receives HTTP 202 outside agent mode, `request()` returns the approval envelope, so this branch reports success with an undefined epoch (or exits 0 with JSON) without revoking sessions. Use `rawRequest()` and `handleApproval()` before formatting the response, as `update()` does.</comment>
<file context>
@@ -0,0 +1,47 @@
+export async function revoke(opts: { json?: boolean }) {
+ 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})`)
</file context>
|
|
||
| export async function projectLink(id: string, opts: { json?: boolean } = {}): Promise<void> { | ||
| const api = await ApiClient.load() | ||
| if (agentMode()) await setupProjectAgentSession(api, id) |
There was a problem hiding this comment.
P2: In projectLink, setupProjectAgentSession(api, id) runs before the GET /projects/{id} validates the id and before writeProject succeeds, so a failed link (typo'd id, no access, network error) still calls POST /agent/sessions and writes a signed .insta/agent-session.json on disk. projectCreate establishes the session only after a successful create+write. Move the call below the GET/link so a failed link doesn't mint/persist agent credentials; it also keeps the two commands' failure behavior consistent.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At src/commands/project.ts, line 102:
<comment>In `projectLink`, `setupProjectAgentSession(api, id)` runs before the `GET /projects/{id}` validates the id and before `writeProject` succeeds, so a failed link (typo'd id, no access, network error) still calls `POST /agent/sessions` and writes a signed `.insta/agent-session.json` on disk. `projectCreate` establishes the session only after a successful create+write. Move the call below the GET/link so a failed link doesn't mint/persist agent credentials; it also keeps the two commands' failure behavior consistent.</comment>
<file context>
@@ -97,6 +99,7 @@ export async function projectList(opts: { org?: string; json?: boolean }): Promi
export async function projectLink(id: string, opts: { json?: boolean } = {}): Promise<void> {
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' })
</file context>
| try { | ||
| const root = await findProjectRoot(cwd) ?? cwd | ||
| const session = JSON.parse(await readFile(join(root, '.insta/agent-session.json'), 'utf8')) as Session | ||
| if (session.projectId !== projectId || session.apiUrl !== apiUrl.replace(/\/+$/, '') || !session.token || !session.privateKey |
There was a problem hiding this comment.
P2: When .insta/agent-session.json is partially corrupted or edited, loadAgentSession accepts it unless token/privateKey/expiry are also missing. agentHeaders then sends an undefined session/client value and fails with an opaque server or fetch error instead of the documented insta setup agent guidance; validate every field used to build the proof, including agentSessionId and client, before returning the session.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At src/agent.ts, line 61:
<comment>When `.insta/agent-session.json` is partially corrupted or edited, `loadAgentSession` accepts it unless token/privateKey/expiry are also missing. `agentHeaders` then sends an `undefined` session/client value and fails with an opaque server or fetch error instead of the documented `insta setup agent` guidance; validate every field used to build the proof, including `agentSessionId` and `client`, before returning the session.</comment>
<file context>
@@ -0,0 +1,86 @@
+ try {
+ const root = await findProjectRoot(cwd) ?? cwd
+ const session = JSON.parse(await readFile(join(root, '.insta/agent-session.json'), 'utf8')) as Session
+ 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
</file context>
| private async fetch(method: string, path: string, body: unknown, auth: boolean): Promise<RawResult> { | ||
| const headers: Record<string, string> = { '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))) |
There was a problem hiding this comment.
P2: In agent mode every authenticated non-project API request mints a fresh bootstrap agent session — an ED25519 keypair and a new POST /agent/sessions round-trip — because agentHeaders() calls issueAgentSession() with no caching on each fetch(). This adds keypair generation plus an extra network request to every such API call (and double-mints after a 401 refresh). Cache the bootstrap session after first issuance (or scope session minting to command start) instead of per request.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At src/api.ts, line 82:
<comment>In agent mode every authenticated non-project API request mints a fresh bootstrap agent session — an ED25519 keypair and a new POST /agent/sessions round-trip — because agentHeaders() calls issueAgentSession() with no caching on each fetch(). This adds keypair generation plus an extra network request to every such API call (and double-mints after a 401 refresh). Cache the bootstrap session after first issuance (or scope session minting to command start) instead of per request.</comment>
<file context>
@@ -74,6 +79,7 @@ export class ApiClient {
private async fetch(method: string, path: string, body: unknown, auth: boolean): Promise<RawResult> {
const headers: Record<string, string> = { '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,
</file context>
| export async function writeProject(c: ProjectConfig, cwd = process.cwd()): Promise<void> { | ||
| const target = (await findProjectRoot(cwd)) ?? cwd | ||
| await mkdir(join(target, PROJECT_DIR), { recursive: true }) | ||
| ensureGitignore(target, ['.insta/agent-session.json'], '# Local agent credentials') |
There was a problem hiding this comment.
P3: This unconditionally creates/updates .gitignore (and creates the file if absent) on every project create/link/auto-link, even for human users who never use agent sessions. The agent-session path (saveAgentSession) already adds this exact ignore entry when a session is actually written, so this forces a repository side effect on all non-agent flows. Consider adding the ignore entry only at session-write time.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At src/config.ts, line 147:
<comment>This unconditionally creates/updates `.gitignore` (and creates the file if absent) on every project create/link/auto-link, even for human users who never use agent sessions. The agent-session path (saveAgentSession) already adds this exact ignore entry when a session is actually written, so this forces a repository side effect on all non-agent flows. Consider adding the ignore entry only at session-write time.</comment>
<file context>
@@ -143,5 +144,6 @@ export async function readProject(cwd = process.cwd()): Promise<ProjectConfig |
export async function writeProject(c: ProjectConfig, cwd = process.cwd()): Promise<void> {
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))
}
</file context>
| // Returns parsed body for status < 400 (incl. 202); throws ApiError otherwise. | ||
| async request<T = any>(method: string, path: string, body?: unknown, opts: { auth?: boolean } = {}): Promise<T> { | ||
| 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) |
There was a problem hiding this comment.
P3: request()'s docstring and the file-header comment say 202/approval_required returns the parsed body, but the new line throws AgentApprovalRequired for 202 in agent mode. Update the comment to note the 202-throws condition in agent mode so the contract isn't misleading.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At src/api.ts, line 59:
<comment>request()'s docstring and the file-header comment say 202/approval_required returns the parsed body, but the new line throws AgentApprovalRequired for 202 in agent mode. Update the comment to note the 202-throws condition in agent mode so the contract isn't misleading.</comment>
<file context>
@@ -52,6 +56,7 @@ export class ApiClient {
// Returns parsed body for status < 400 (incl. 202); throws ApiError otherwise.
async request<T = any>(method: string, path: string, body?: unknown, opts: { auth?: boolean } = {}): Promise<T> {
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 as T
</file context>
| } | ||
| } | ||
| if (loggedIn) { | ||
| if (await enroll()) info('✓ Project agent session ready (expires in 24 hours; refresh with insta setup agent)') |
There was a problem hiding this comment.
P3: Under agent mode, insta setup agent --project/--create enrolls twice: projectLink/projectCreate already call setupProjectAgentSession(api, id) (src/commands/project.ts:78/:102), and then setup.ts calls enroll() again for the same project, issuing a second /agent/sessions request/keypair and overwriting the session file. Skip the project-step enrollment when the later enroll() will run, or skip enroll() when the project step already enrolled, to avoid the duplicate issuance.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At src/commands/setup.ts, line 491:
<comment>Under agent mode, `insta setup agent --project/--create` enrolls twice: projectLink/projectCreate already call setupProjectAgentSession(api, id) (src/commands/project.ts:78/:102), and then setup.ts calls enroll() again for the same project, issuing a second `/agent/sessions` request/keypair and overwriting the session file. Skip the project-step enrollment when the later enroll() will run, or skip enroll() when the project step already enrolled, to avoid the duplicate issuance.</comment>
<file context>
@@ -485,6 +487,11 @@ export async function setupAgent(
}
}
+ 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`')
</file context>
| } | ||
| export async function rule(action: string, decision: string, opts: { json?: boolean }) { | ||
| if (!['allow', 'deny', 'approve'].includes(decision)) throw new Error('decision must be allow, deny, or approve') | ||
| return update(policy => { policy.branchDeveloperRules[action] = decision }, opts) |
There was a problem hiding this comment.
P3: When the platform policy payload lacks branchDeveloperRules, rule() throws a TypeError instead of setting the rule. Guard the field before assigning: policy.branchDeveloperRules ??= {} so the command works on any policy shape.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At src/commands/agent-policy.ts, line 39:
<comment>When the platform policy payload lacks `branchDeveloperRules`, `rule()` throws a TypeError instead of setting the rule. Guard the field before assigning: `policy.branchDeveloperRules ??= {}` so the command works on any policy shape.</comment>
<file context>
@@ -0,0 +1,47 @@
+}
+export async function rule(action: string, decision: string, opts: { json?: boolean }) {
+ 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: { json?: boolean }) {
</file context>
Suggested change
| return update(policy => { policy.branchDeveloperRules[action] = decision }, opts) | |
| return update(policy => { (policy.branchDeveloperRules ??= {})[action] = decision }, opts) |
| const { branches } = await api.request('GET', `/projects/${project.projectId}/branches`) | ||
| const found = branches.find((b: any) => 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: string) => id !== found.id) |
There was a problem hiding this comment.
P3: When the platform policy payload lacks protectedBranchIds, protect() throws on [...policy.protectedBranchIds, ...] / policy.protectedBranchIds.filter(...). Default the field to an array before reading it, matching the get() output that already treats an empty list as '(none)'.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At src/commands/agent-policy.ts, line 34:
<comment>When the platform policy payload lacks `protectedBranchIds`, `protect()` throws on `[...policy.protectedBranchIds, ...]` / `policy.protectedBranchIds.filter(...)`. Default the field to an array before reading it, matching the `get()` output that already treats an empty list as '(none)'.</comment>
<file context>
@@ -0,0 +1,47 @@
+ const { branches } = await api.request('GET', `/projects/${project.projectId}/branches`)
+ const found = branches.find((b: any) => 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: string) => id !== found.id)
+ }, opts)
+}
</file context>
Suggested change
| policy.protectedBranchIds = enabled ? [...new Set([...policy.protectedBranchIds, found.id])] : policy.protectedBranchIds.filter((id: string) => id !== found.id) | |
| const ids = policy.protectedBranchIds ?? [] | |
| policy.protectedBranchIds = enabled ? [...new Set([...ids, found.id])] : ids.filter((id: string) => id !== found.id) |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Validation
Dependencies and rollout
Requires the companion insta-platform agent-governance change before release. Companion insta-skills changes document explicit --agent invocations. No production deployment or release is included.
Summary by cubic
Adds
--agentmode with signed, project-bound sessions and newagent-policygovernance commands. Agent requests now fail closed when no valid session exists, and 202 approval responses surface as errors instead of being treated as completed.Changes
--agentflag and environment-based detection for Codex, Claude Code, and Cursor.insta setup agent, stored with 0600 permissions and gitignored.AgentApprovalRequiredon 202 approval responses instead of returning them as success.agent-policycommands: get, set mode, protect/unprotect branches, set rules, revoke sessions.compute execarguments when--agentis used.Rollout
insta-platformagent-governance change before release.Written for commit 4480626. Summary will update on new commits.