pnpm add @gao/system-sdk

import { GaoSDK, GaoAuth } from '@gao/system-sdk'

// Initialize SDK
const sdk = new GaoSDK({
  domain: 'myapp.gao',
  apiKey: process.env.GAO_API_KEY,
  environment: 'production', // or 'testnet'
})

// Auth with Passkey
const auth = new GaoAuth()
const assertion = await auth.login()
const { domain, token } = await auth.completeLogin(assertion)
const sdk = new GaoSDK({ domain, token })

---

### sdk.developer — Capability & Connectors (L3)

#### Capability Tokens

// Request a capability token
const cap = await sdk.developer.capability.request(
  capability: string,   // e.g. 'intelligence:agent:run'
  domain: string,       // your app domain
  ttlSeconds?: number   // default 3600
): `Promise<CapabilityToken>`
// Validate a token
await sdk.developer.capability.validate(token: string): `Promise<CapabilityValidation>`
// Revoke a token
await sdk.developer.capability.revoke(tokenId: string): Promise`<void>`

#### Connectors

// List available connectors
await sdk.developer.connectors.list(): Promise<Connector[]>
// Execute a connector action
await sdk.developer.connectors.execute(
  connectorId: string,   // 'gmail' | 'slack' | 'meshii' | 'payii' | 'webhook'
  action: string,        // connector-specific action name
  payload: unknown,
  capability: string
): `Promise<ConnectorResult>`

**Available connectors:** `gmail`, `slack`, `meshii` (Gao-native), `payii` (Gao-native), `webhook`, `github`, `notion`, `airtable`

---

### sdk.identity — Domain Layer (L5)

// Resolve a .gao domain (read-only, publicly verifiable)
const record = await sdk.identity.resolve('alice.gao'): `Promise<DomainRecord>`

interface DomainRecord {
  domain:          string   // "alice.gao"
  owner_address:   string   // EVM address
  public_key:      string   // Ed25519 public key
  records:         `Record<string, string>`
  agent_metadata?: AgentMeta
  chain:           string
  updated_at:      number
}
// Get address for a specific chain
await sdk.identity.getAddress('alice.gao', 'base'): Promise`<string>`
// Verify domain ownership
await sdk.identity.isOwner('alice.gao', walletAddress): Promise`<boolean>`
// Verify a signature (challenge-response auth)
await sdk.identity.verifySignature(
  domain: string,
  message: string,
  signature: string
): Promise`<boolean>`
// Get agent metadata (AIP-01)
await sdk.identity.getAgentMeta('alice.gao'): `Promise<AgentMeta>`
// Publish agent metadata
await sdk.identity.publishAgentMeta('alice.gao', meta: AgentMeta): Promise`<void>`

// Create payment intent
const intent = await sdk.settlement.createIntent({
  amount:           string,          // "25.00"
  currency:         'USDC'|'USDT'|'GAO'|'USD',
  recipient:        string,          // "merchant.gao"
  description?:     string,
  idempotency_key:  string,          // crypto.randomUUID() — always unique
  capability:       string,          // capability token
}): Promise<PaymentIntent>

// Get receipt
await sdk.settlement.getReceipt(intentId: string): Promise<PaymentReceipt>

// Validate receipt (always call this before fulfilling)
await sdk.settlement.validateReceipt(receipt: PaymentReceipt): Promise<boolean>

// Watch for on-chain finality
await sdk.settlement.watchFinality(intentId: string): Promise<FinalityEvent>

// Budget management
await sdk.settlement.budget.get(domain: string): Promise<BudgetStatus>
await sdk.settlement.budget.check(domain: string, amount: string): Promise<boolean>

// x402 sub-module (HTTP 402 payment flows)
await sdk.settlement.x402.createProof(amount, currency, recipient): Promise<string>
await sdk.settlement.x402.verifyProof(proof: string): Promise<boolean>

---

### sdk.transport — Messaging Layer (L6)

All messages are end-to-end encrypted via Meshii Protocol. No server stores message history by default.

// Send a message
await sdk.transport.message.send({
  to:          string,                                     // "alice.gao" or routing tag
  content:     string,
  type?:       'text' | 'notification' | 'agent_action',  // default 'text'
  encrypted?:  boolean,                                    // default true
}): Promise`<void>`
// Subscribe to incoming messages
const unsub = sdk.transport.message.subscribe(
  handler: (msg: IncomingMessage) => void
): UnsubscribeFn
// Call unsub() to stop receiving
// Agent sends as bot identity
await sdk.transport.message.sendAsAgent(
  agentId:  string,
  to:       string,
  content:  string
): Promise`<void>`
// Routing helpers
await sdk.transport.selectRoute(params: RouteParams): `Promise<RouteResult>`
await sdk.transport.validateRelayPath(path: string[]): Promise`<boolean>`

// Upload to GaoStorage
const receipt = await sdk.infrastructure.storage.upload(
  data:  Uint8Array | string,
  opts?: {
    encrypted?:    boolean,   // default true
    ttl_days?:     number,    // null = permanent
    redundancy?:   number,    // default 3
    content_type?: string,
  }
): Promise<StorageReceipt>

// Download
await sdk.infrastructure.storage.download(cid: string): Promise<Uint8Array>

// Delete
await sdk.infrastructure.storage.delete(cid: string): Promise<void>

// Pin (keep permanently)
await sdk.infrastructure.storage.pin(cid: string): Promise<void>

// Submit compute job
const receipt = await sdk.infrastructure.compute.submit({
  runtime:          'python' | 'node' | 'wasm',
  code:             string,
  input?:           unknown,
  timeout_seconds:  number,
  capability:       string,
}): Promise<ComputeReceipt>

// Get compute result
await sdk.infrastructure.compute.getResult(jobId: string): Promise<ComputeResult>

// Validate compute receipt
await sdk.infrastructure.compute.validateReceipt(receipt: ComputeReceipt): Promise<boolean>

---

### sdk.intelligence — AI OS Layer (L8)

#### Agent Lifecycle

// Create agent from manifest
const agent = await sdk.intelligence.createAgent(manifest: AgentManifest): `Promise<Agent>`
// Run agent (batch)
const session = await sdk.intelligence.runAgent(
  agentId: string,
  intent:  string
): `Promise<GARSession>`
// Run agent (streaming — recommended)
for await (const chunk of sdk.intelligence.runAgentStream(agentId, intent)) {
  // chunk.type: 'text' | 'tool_use' | 'artifact' | 'step' | 'done'
  if (chunk.type === 'text')     appendText(chunk.delta)
  if (chunk.type === 'artifact') showArtifact(chunk)
  if (chunk.type === 'done')     finalize()
}
// Pause / revoke
await sdk.intelligence.pauseAgent(agentId: string): Promise`<void>`
await sdk.intelligence.revokeAgent(agentId: string): Promise`<void>`

#### Sessions

// Get session
await sdk.intelligence.getSession(sessionId: string): `Promise<GARSession>`
// Watch session in real time
for await (const event of sdk.intelligence.watchSession(sessionId)) {
  // event.type: 'state_change' | 'task_complete' | 'artifact' | 'error'
}

#### Tools

await sdk.intelligence.tools.call(
  toolName:   string,
  input:      unknown,
  capability: string
): `Promise<ToolResult>`

#### Artifacts

await sdk.intelligence.artifacts.list(domain: string): Promise<Artifact[]>
await sdk.intelligence.artifacts.get(artifactId: string): `Promise<Artifact>`
await sdk.intelligence.artifacts.download(artifactId: string): `Promise<Uint8Array>`

#### Scheduler

// Create scheduled job
const job = await sdk.intelligence.scheduler.create({
  agent_id:          string,
  owner_domain:      string,
  trigger_type:      'cron' | 'webhook' | 'event' | 'interval' | 'threshold',
  trigger_config:    object,    // e.g. { expression: '0 9 * * *', timezone: 'America/Chicago' }
  priority?:         'low' | 'normal' | 'high',
  retry_policy?:     { max_retries: number, backoff: 'exponential' | 'linear' },
  execution_target?: 'server' | 'depin',
}): `Promise<SchedulerJob>`

await sdk.intelligence.scheduler.pause(jobId: string): Promise`<void>`
await sdk.intelligence.scheduler.resume(jobId: string): Promise`<void>`
await sdk.intelligence.scheduler.delete(jobId: string): Promise`<void>`

// Agent management
await sdk.workspace.agents.list(domain: string): Promise<Agent[]>
await sdk.workspace.agents.get(agentId: string): Promise<Agent>
await sdk.workspace.agents.pause(agentId: string): Promise<void>
await sdk.workspace.agents.revoke(agentId: string): Promise<void>

// Policy management
await sdk.workspace.policy.get(domain: string): Promise<PolicyProfile>
await sdk.workspace.policy.update(domain: string, policy: PolicyProfile): Promise<void>

// Audit log
await sdk.workspace.audit.list(
  domain: string,
  opts?: { limit?: number, since?: string, event_type?: string }
): Promise<AuditEvent[]>

// Real-time audit stream
for await (const event of sdk.workspace.audit.stream(domain)) {
  console.log(event.event_type, event.outcome)
}

---

### React Hooks

import { useGao, useAgent, usePayment, useIdentity } from '@gao/system-sdk/react'

function BookingApp() {
  const { sdk, ready }                   = useGao({ domain: 'myapp.gao', apiKey })
  const { run, session, streaming }      = useAgent(sdk, 'booking-agent-id')
  const { createIntent, receipt, loading } = usePayment(sdk)
  const { resolve, identity }            = useIdentity(sdk)

  const handleBook = async () => {
    // Verify customer identity
    const customer = await resolve('alice.gao')
    // Run booking agent
    await run('Book appointment for tomorrow 3pm')
    // Process payment
    await createIntent({
      amount: '25.00',
      currency: 'USDC',
      recipient: 'merchant.gao',
      idempotency_key: crypto.randomUUID(),
      capability: 'settlement:intent:create',
    })
  }

  if (!ready) return <Skeleton />
  return <Button onClick={handleBook}>Book Now</Button>
}

interface AgentManifest {
  agent_id:              string
  name:                  string
  owner_domain:          string       // "merchant.gao"
  version:               string       // "1.0.0"
  description:           string
  purpose:               string       // normalized purpose class
  risk_tier_default:     'LOW' | 'MEDIUM' | 'HIGH'
  allowed_capabilities:  string[]     // list of capability strings
  policy_profile_id?:    string
  memory_profile_id?:    string
  model_profile_id?:     string
  tool_set_id?:          string
  deployment_profile_id?: string
  status:                'draft' | 'active' | 'paused' | 'revoked'
}

---

### Error Reference

Code

Meaning

Resolution

`GAO-4001`

Capability expired

Re-request capability token

`GAO-4002`

Budget exceeded

Check Studio billing

`GAO-4003`

Route unavailable

Retry with exponential backoff

`GAO-4004`

Finality timeout

Check receipt status separately

`GAO-4005`

Receipt invalid

Abort — do not retry

`GAO-4006`

Replay detected

Generate new `idempotency_key`

`GAO-4007`

Policy snapshot mismatch

Reload policy profile

`GAO-4008`

Reputation update failed

Non-blocking — log only

`GAO-4009`

Capability expired mid-flight

Re-request and retry

---

### Versioning

SDK follows semantic versioning with AIP compatibility matrix:

SDK Version

AIP Compatibility

Notes

GS/1.0.0

AIP-01 to AIP-10

Initial release

GS/1.1.0

AIP-01 to AIP-16

Additive — no breaking changes

GS/1.1.1

AIP-01 to AIP-18

Current stable

Breaking changes require major version bump + 28-day governance notice.

---

### Next Steps

-   API Reference — REST endpoints for direct integration
    
-   Example Apps — complete working dApps
    
-   Gao Studio — build and deploy agents visually