Storage API

Read and write files in the user's METAOS storage.

💡 Scoped Access: Use manifest scopes to limit storage paths your agent can access.

storage.read()

Read file contents from user's storage.

Parameters

Parameter	Type	Required	Description
`path`	string	Yes	File path (metaos:// URI)

Example

const content = await tools.storage.read({
  path: "metaos://notes/travel/trip-plan.md"
});

// Returns:
{
  path: "metaos://notes/travel/trip-plan.md",
  content: "# Paris Trip

Flight: AF123...",
  contentType: "text/markdown",
  size: 1024,
  lastModified: "2024-03-15T10:30:00Z"
}

storage.write()

Write or update file contents in user's storage.

Parameters

Parameter	Type	Required	Description
`path`	string	Yes	File path (metaos:// URI)
`content`	string	Yes	File content to write
`contentType`	string	No	MIME type (default: text/plain)

Example

await tools.storage.write({
  path: "metaos://notes/travel/packing-list.md",
  content: "# Packing List\n- Passport\n- Tickets\n- Camera",
  contentType: "text/markdown"
});

// Returns:
{
  path: "metaos://notes/travel/packing-list.md",
  size: 56,
  lastModified: "2024-03-15T14:00:00Z"
}

Path Scoping

Limit your agent's storage access using manifest scopes:

{
  "capabilities": ["storage.read", "storage.write"],
  "scopes": {
    "storage.read": ["metaos://notes/travel/*"],
    "storage.write": ["metaos://notes/travel/*"]
  }
}

With this scope, your agent can only access files under metaos://notes/travel/. Attempts to read/write other paths will throw SCOPE_VIOLATION.

Complete Example

export async function handleIntent({ intent, context, tools }) {
  // Save a note
  if (intent.action === "save_note") {
    const { title, content } = intent.parameters;
    
    await tools.storage.write({
      path: `metaos://notes/${title}.md`,
      content: content,
      contentType: "text/markdown"
    });

    return {
      type: "result",
      title: "✅ Note saved",
      description: `Saved "${title}"`
    };
  }

  // List all notes
  if (intent.action === "list_notes") {
    const files = await tools.storage.list({
      path: "metaos://notes/"
    });

    return {
      type: "summary",
      title: "Your Notes",
      items: files.map(f => ({
        title: f.name,
        subtitle: f.lastModified
      }))
    };
  }

  // Read a note
  if (intent.action === "read_note") {
    const { name } = intent.parameters;
    
    const file = await tools.storage.read({
      path: `metaos://notes/${name}.md`
    });

    return {
      type: "result",
      title: name,
      description: file.content
    };
  }
}

Required Capabilities

{
  "capabilities": [
    "storage.read",   // for storage.read(), storage.list()
    "storage.write"   // for storage.write()
  ]
}

Error Codes

CAPABILITY_DENIED

User has not granted storage.read or storage.write capability.

SCOPE_VIOLATION

Attempting to access path outside manifest scopes.

FILE_NOT_FOUND

File does not exist at specified path.

STORAGE_QUOTA_EXCEEDED

User's storage quota is full.