ambleloftPages, agents and operations
One implementation, available to a page and to the agent.
Outcome: Register an operation and verify page calls and failure handling.
Before you begin: Prepare the files and tools specified on this page. The previous page in the learning path is not automatically a dependency.
On this page
01Register a Node handler
Register synchronously during activate. Use resources bound to the current invocation. This code comes from the existing project-card example.
import { defineExtension } from '@ambleloft/extension-sdk';
export const { activate } = defineExtension({
activate(context) {
context.subscriptions.push(
context.operations.register('describeProject',
async (input, invocation) => {
const project = await invocation.resources
.getProject(input.projectId as string);
return { ...project };
}
)
);
}
});02Declare the manifest
Declare main, permissions, operation ID, matching handler and input/output schemas in extension.json. exposeTo: ["page", "agent"] enables both entry points. Project reads require projects.read and project binding.
03Invoke from a page
Use the webview entry. Initialize before selecting a project and invoking. This bridge only works inside the desktop extension page.
import { createClient, unwrap } from '@ambleloft/extension-sdk/webview';
const client = createClient();
await client.initialize();
const project = unwrap(await client.selectProject({
capabilities: ['projects.read']
}));
if (project) {
const result = await client.invoke('example.project-card.describe', {
projectId: project.id
});
if (result.ok) console.log(result.value);
else console.error(result.error.code);
}04Handle failures and cancellation
Preview capability · SDK 0.1.0-alpha.9
Cancellation stops waiting; it does not roll back writes. Never automatically retry an unknown effectStatus. Dispose page subscriptions and detect actual host methods for preview capabilities.
Check the result and troubleshoot
Register an operation and verify page calls and failure handling.
Check actual results using this page’s verification steps. For business integrations, inspect UI submission, tool receipts and server records separately.
Open the error reference →