@filepad/agent-access-sdk

@filepad/agent-access-sdk

Official SDK for connecting external AI agents to Filepad workspaces via Agent Access.

What is Agent Access?

Agent Access is Filepad's scoped API for external agents. It lets an outside agent:

• Read workspace context (folders, files, skills, search)
• Read visible workspace signals
• Read and propose updates to the agent's own home profile
• Create governed artifacts under artifacts/ when intentionally granted
• Propose reviewable edits to allowed files
• Report activity events
• Receive addressed mailbox notifications from Filepad
• Discover and call governed RuntimeTools, including Gmail read/action tools when granted

Agent Access does not let external agents directly mutate active workspace files, approve their own proposals, send email, run compute, or execute automations without Filepad governance.

Install

npm install @filepad/agent-access-sdk

Requires Node.js 18+.

Quick Start

import { FilepadAgentClient } from '@filepad/agent-access-sdk';

const client = new FilepadAgentClient({
  baseUrl: 'https://api.filepad.ai',
  workspaceId: 'ws_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
  keyId: 'ik_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
  secret: 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
});

// Start here: one-call onboarding and resume diagnostics
const connected = await client.connect();
console.log('Workspace:', connected.workspace.displayName);
console.log('Granted scopes:', connected.scopes);
console.log('Visible tools:', connected.tools.map(tool => tool.providerName));
console.log('Suggested first actions:', connected.bootstrap.suggestedFirstActions);

// For native-memory runtimes, hydrate the planner with connected.bootstrap,
// connected.mailbox and connected.recentOutcomes before work.
// `client.bootstrap()` is an alias that calls the HTTP /bootstrap endpoint and
// returns the same payload.

// Read environment
const env = await client.getEnvironment();
console.log('Folders:', env.folders.map(f => f.name));

// Search workspace
const search = await client.search('quarterly report', { type: 'keyword', limit: 5 });
console.log('Results:', search.results.length);

// Create a governed artifact when the key is trusted for direct artifact creation
const { artifact } = await client.createArtifact({
  title: 'Agent Report',
  text: '# Summary\n\nGenerated by external agent.',
  kind: 'auto',
  format: 'markdown',
});
console.log('Artifact:', artifact.id);

// Emit event
const { eventId } = await client.createEvent({
  eventType: 'agent.task.completed',
  payload: { artifactId: artifact.id },
});
console.log('Event:', eventId);

// Query visible signals
const signals = await client.getSignals({ status: 'suggested', limit: 10 });
console.log('Signals:', signals.signals.length);
if (signals.signals[0]) {
  const signal = await client.getSignal(signals.signals[0].id);
  console.log('Signal:', signal.findingTypeKey, signal.status);
}

// Read Filepad callbacks addressed to this integration
const mailbox = await client.getMailbox({ unreadOnly: true, limit: 20 });
console.log('Unread mailbox items:', mailbox.items.length);
if (mailbox.items.length > 0) {
  await client.ackMailbox(mailbox.items.map(item => item.id));
}

// Read this key's agent home profile
const profile = await client.getAgentProfile();
console.log('Agent profile key:', profile.keyId);

// Discover governed tools, import a synced email if useful, and request a Gmail send through approval
const tools = await client.listTools();
console.log('Visible tools:', tools.tools.map(tool => tool.providerName));
const importedEmail = await client.importGmailMessage({
  externalId: 'gmail_message_id',
});
console.log('Gmail import:', importedEmail.output);
const gmailReply = await client.sendGmailWithApproval({
  sourceRecordId: 'src_gmail_message',
  toAddresses: ['[e-mail]'],
  subject: 'Re: Renewal question',
  bodyText: 'Thanks for reaching out. Here are the next steps.',
});
console.log('Gmail approval request:', gmailReply.output);

Authentication

Every request is signed with HMAC-SHA256 using your Agent Access key.

Create a key in Filepad:

• Open a workspace
• Go to Settings → Agent Access
• Click Create Key
• Copy the Key ID and Secret (shown once)

The SDK handles signing automatically. You only need to provide keyId and secret to the client.

API Reference

FilepadAgentClient

verifyCredentials()

Returns the integration key id, integration id, workspace id, and granted scopes.

connect()

Returns onboarding/resume diagnostics: identity, workspace, granted scopes, recommended missing scopes, available RuntimeTools, agent home, unread mailbox, recent outcomes, tool groups, and suggested first actions. Agents should call this first and when resuming work.

bootstrap()

Alias for connect() that calls the HTTP /bootstrap endpoint. Use this when a runtime or fallback path is explicitly looking for a bootstrap handshake.

getEnvironment()

Returns workspace folders and their status.

getFileTree()

Returns all visible files and folders.

getFile(fileNodeId)

Reads a file by its node id.

getPrompts() / getMcpPrompts() / getMcpResources()

Discover skills and resources.

search(query, options?)

Search indexed workspace context.

createArtifact(params)

Create a governed artifact under artifacts/ when the key has tools:call and artifacts:direct_write. Use kind: "auto" and format: "markdown" when producing markdown that should become a rich document.

proposeEdit(params)

Propose a reviewable edit to an allowed file.

createEvent(params)

Emit an activity event.

createSignal(params)

Create a signal (requires signals:write scope).

getSignals(filters?)

Query visible workspace signals by type, severity, status, limit, or cursor. Requires env:read.

getSignal(signalId)

Read one visible workspace signal by id. Requires env:read.

getMailbox(options?)

Read Filepad mailbox notifications addressed to this integration. Requires notifications:read.

ackMailbox(ids)

Acknowledge processed mailbox notification ids. Requires notifications:read.

getAgentProfile(options?)

Read this integration's agent home profile files under agents/integrations/{keyId}/. Requires env:read.

updateAgentProfile(params)

Propose an append or replacement update to one profile file. Requires env:read and files:propose; the change waits for human review.

listTools() / callTool(params)

Discover and call Filepad's canonical governed RuntimeTool catalog. Tool visibility is filtered by workspace role, scopes, connected providers, tier, and policy.

searchGmail(params) / getGmailMessage(params)

Read synced Gmail source records through the governed tool bridge. Requires tools:read/tools:call and gmail:read scopes.

importGmailMessage(params) / createGmailDraft(params) / sendGmailWithApproval(params)

Request Gmail imports, drafts, or sends through Filepad governance. Sends always create an approval-backed outbound action; agents do not receive raw Gmail credentials. Requires tools:call and gmail:write.

Error Handling

The SDK throws typed errors:

• AuthenticationError — invalid signature or expired key
• ForbiddenScopeError — missing required scope
• NotFoundError — file or resource not found
• RateLimitError — too many requests
• ProposalPathError — proposal target is not allowed
• StaleVersionError — base version changed during proposal

All errors extend FilepadAgentError with code, message, and status properties.

import { FilepadAgentError, AuthenticationError } from '@filepad/agent-access-sdk';

try {
  await client.getFile('fn_...');
} catch (err) {
  if (err instanceof AuthenticationError) {
    console.error('Check your key id and secret');
  } else if (err instanceof FilepadAgentError) {
    console.error(err.code, err.message);
  }
}

Scope Reference

Scope	What it allows
env:read	Read folders, file tree, file content, search, skill prompts, MCP resources, and visible signals
artifacts:direct_write	Create artifacts under artifacts/ when intentionally granted
files:propose	Create reviewable edit proposals for allowed files
memory:read	Read memory entries
events.write	Write agent activity events
signals:write	Create signals for automation triggers
notifications:read	Read and acknowledge Filepad mailbox notifications addressed to this integration
tools:read	Discover governed RuntimeTools
tools:call	Call governed RuntimeTools
gmail:read	Read synced Gmail source records through RuntimeTools
gmail:write	Request Gmail imports, drafts, and sends through governed approval workflows
github:read	Read synced GitHub source records through RuntimeTools
github:write	Request governed GitHub actions when enabled

License

MIT