availsync 0.1.0

package/packages/mcp/src/index.ts

@@ -0,0 +1,387 @@
+#!/usr/bin/env node
+
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { fileURLToPath } from 'url';
+import { z } from 'zod';
+import { configuredAgentId, idempotencyHeaders, parseResponseBody, requireAgentId } from './helpers.js';
+
+type JsonObject = Record<string, unknown>;
+
+function printHelp(): void {
+  console.log(`Availsync MCP server
+
+Environment:
+  AVAILSYNC_API_URL    Base URL for Availsync, default https://availsync.dev
+  AVAILSYNC_AGENT_ID   Default agent UUID shown in the Availsync dashboard
+  AVAILSYNC_API_KEY    Agent API key, stored as a runtime secret
+
+Tools:
+  check_availability  Check available slots before booking
+  preview_conflict    Preview who would win before booking
+  book_slot           Reserve a slot
+  release_slot        Release a booked hold
+  check_work_slot     Check whether a coding agent can work on a repo/project
+  claim_work_slot     Start a guarded repo/project run before a coding agent starts
+  extend_work_slot    Extend a guarded run claim while the agent is still working
+  release_work_slot   Finish a guarded run claim
+  diagnose_availsync_setup  Check local MCP env setup without exposing secrets
+
+Status:
+  The server sends a heartbeat to Availsync on startup and then every 60 seconds.
+
+Production flow:
+  heartbeat -> check_work_slot -> claim_work_slot -> extend_work_slot while working -> release_work_slot
+
+Notes:
+  Tool input agent_id is optional when AVAILSYNC_AGENT_ID is set.
+  claim_work_slot uses /v1/work/run/start, so observe-mode agents proceed and report shadow decisions.
+`);
+}
+
+function getConfig(): { apiUrl: string; apiKey: string; agentId: string | null } {
+  const apiUrl = process.env.AVAILSYNC_API_URL || 'https://availsync.dev';
+  const apiKey = process.env.AVAILSYNC_API_KEY;
+
+  if (!apiKey) {
+    throw new Error('AVAILSYNC_API_KEY is required');
+  }
+
+  return { apiUrl: apiUrl.replace(/\/$/, ''), apiKey, agentId: configuredAgentId() };
+}
+
+async function requestAvailsync(
+  method: string,
+  path: string,
+  body?: JsonObject,
+  extraHeaders: Record<string, string> = {},
+): Promise<unknown> {
+  const { apiUrl, apiKey } = getConfig();
+  const response = await fetch(`${apiUrl}${path}`, {
+    method,
+    headers: {
+      Authorization: `Bearer ${apiKey}`,
+      'Content-Type': 'application/json',
+      ...extraHeaders,
+    },
+    body: body ? JSON.stringify(body) : undefined,
+  });
+
+  const text = await response.text();
+  const payload = parseResponseBody(text, response);
+
+  if (!response.ok) {
+    return {
+      status: response.status,
+      error: payload,
+    };
+  }
+
+  return payload;
+}
+
+async function sendHeartbeat(): Promise<void> {
+  await requestAvailsync('POST', '/v1/mcp/heartbeat', {
+    client_name: 'availsync-mcp',
+  });
+}
+
+function jsonContent(payload: unknown) {
+  return {
+    content: [
+      {
+        type: 'text' as const,
+        text: JSON.stringify(payload, null, 2),
+      },
+    ],
+  };
+}
+
+const usageSchema = z
+  .object({
+    provider: z.string().optional(),
+    model: z.string().optional(),
+    input_tokens: z.number().int().min(0).optional(),
+    output_tokens: z.number().int().min(0).optional(),
+    total_tokens: z.number().int().min(0).optional(),
+    estimated_cost_usd: z.number().min(0).optional(),
+  })
+  .optional();
+
+const optionalAgentIdSchema = z
+  .string()
+  .uuid()
+  .optional()
+  .describe('UUID of the agent. Optional when AVAILSYNC_AGENT_ID is set in the MCP server environment.');
+
+async function reportUsage(activityType: string, usage?: z.infer<typeof usageSchema>): Promise<void> {
+  if (!usage) return;
+  await requestAvailsync('POST', '/v1/activity/usage', {
+    activity_type: activityType,
+    client_name: 'availsync-mcp',
+    ...usage,
+  });
+}
+
+function createServer(): McpServer {
+  const server = new McpServer({
+    name: 'availsync',
+    version: '0.1.0',
+  });
+
+  server.registerTool(
+    'diagnose_availsync_setup',
+    {
+      description: 'Check local Availsync MCP environment setup without exposing API keys.',
+      inputSchema: {},
+    },
+    async () => jsonContent({
+      api_url: process.env.AVAILSYNC_API_URL || 'https://availsync.dev',
+      agent_id_configured: Boolean(configuredAgentId()),
+      api_key_configured: Boolean(process.env.AVAILSYNC_API_KEY),
+      notes: [
+        'Set AVAILSYNC_AGENT_ID to avoid passing agent_id on every tool call.',
+        'Set AVAILSYNC_API_KEY as a runtime secret. It is never returned by this diagnostic.',
+      ],
+    }),
+  );
+
+  server.registerTool(
+    'check_availability',
+    {
+      description:
+        'Check available time slots for an AI scheduling agent before booking. Always call this before book_slot.',
+      inputSchema: {
+        agent_id: optionalAgentIdSchema,
+        from: z.string().datetime().describe('Start of search window (ISO 8601 UTC)'),
+        to: z.string().datetime().describe('End of search window (ISO 8601 UTC)'),
+        duration_minutes: z.number().describe('Required meeting duration in minutes'),
+        usage: usageSchema,
+      },
+    },
+    async ({ agent_id, from, to, duration_minutes, usage }) => {
+      const query = new URLSearchParams({
+        agent_id: requireAgentId(agent_id),
+        from,
+        to,
+        duration_minutes: String(duration_minutes),
+      });
+      const result = await requestAvailsync('GET', `/v1/availability?${query.toString()}`);
+      await reportUsage('mcp_check_availability', usage);
+      return jsonContent(result);
+    },
+  );
+
+  server.registerTool(
+    'preview_conflict',
+    {
+      description:
+        'Preview whether a proposed slot would be available, win, or lose before booking. Call this after check_availability and before book_slot.',
+      inputSchema: {
+        agent_id: optionalAgentIdSchema,
+        start_at: z.string().datetime(),
+        end_at: z.string().datetime(),
+        reason: z.string().max(500).optional(),
+        usage: usageSchema,
+      },
+    },
+    async ({ agent_id, start_at, end_at, reason, usage }) => {
+      const result = await requestAvailsync('POST', '/v1/conflicts/check', {
+        agent_id: requireAgentId(agent_id),
+        start_at,
+        end_at,
+        ...(reason ? { reason } : {}),
+      });
+      await reportUsage('mcp_preview_conflict', usage);
+      return jsonContent(result);
+    },
+  );
+
+  server.registerTool(
+    'book_slot',
+    {
+      description:
+        'Reserve a time slot. Returns confirmed hold or 409 with alternative suggestions if slot is taken by higher-priority agent.',
+      inputSchema: {
+        agent_id: optionalAgentIdSchema,
+        start_at: z.string().datetime(),
+        end_at: z.string().datetime(),
+        reason: z.string().max(500).optional(),
+        usage: usageSchema,
+      },
+    },
+    async ({ agent_id, start_at, end_at, reason, usage }) => {
+      const result = await requestAvailsync('POST', '/v1/holds', {
+        agent_id: requireAgentId(agent_id),
+        start_at,
+        end_at,
+        ...(reason ? { reason } : {}),
+      });
+      await reportUsage('mcp_book_slot', usage);
+      return jsonContent(result);
+    },
+  );
+
+  server.registerTool(
+    'release_slot',
+    {
+      description: 'Release a previously booked hold so other agents can use the time.',
+      inputSchema: {
+        hold_id: z.string().uuid(),
+        usage: usageSchema,
+      },
+    },
+    async ({ hold_id, usage }) => {
+      const result = await requestAvailsync('DELETE', `/v1/holds/${hold_id}`);
+      await reportUsage('mcp_release_slot', usage);
+      return jsonContent(result);
+    },
+  );
+
+  server.registerTool(
+    'check_work_slot',
+    {
+      description:
+        'Check whether a coding agent can work on a repo or project before it starts. If status is would_lose, skip the run.',
+      inputSchema: {
+        agent_id: optionalAgentIdSchema,
+        resource_type: z.enum(['repo', 'project']),
+        resource_key: z.string().min(1),
+        label: z.string().optional(),
+        start_at: z.string().datetime().optional(),
+        duration_minutes: z.number().int().min(1).max(240).optional(),
+        reason: z.string().max(500).optional(),
+        usage: usageSchema,
+      },
+    },
+    async ({ agent_id, resource_type, resource_key, label, start_at, duration_minutes, reason, usage }) => {
+      const result = await requestAvailsync('POST', '/v1/work/check', {
+        agent_id: requireAgentId(agent_id),
+        resource_type,
+        resource_key,
+        ...(label ? { label } : {}),
+        ...(start_at ? { start_at } : {}),
+        ...(duration_minutes ? { duration_minutes } : {}),
+        ...(reason ? { reason } : {}),
+      });
+      await reportUsage('mcp_check_work_slot', usage);
+      return jsonContent(result);
+    },
+  );
+
+  server.registerTool(
+    'claim_work_slot',
+    {
+      description:
+        'Start a guarded repo/project run before a coding agent starts. Returns proceed, skip_run, or observe-mode shadow details.',
+      inputSchema: {
+        agent_id: optionalAgentIdSchema,
+        resource_type: z.enum(['repo', 'project']),
+        resource_key: z.string().min(1),
+        label: z.string().optional(),
+        start_at: z.string().datetime().optional(),
+        duration_minutes: z.number().int().min(1).max(240).optional(),
+        reason: z.string().max(500).optional(),
+        idempotency_key: z.string().min(1).max(200).optional(),
+        usage: usageSchema,
+      },
+    },
+    async ({ agent_id, resource_type, resource_key, label, start_at, duration_minutes, reason, idempotency_key, usage }) => {
+      const result = await requestAvailsync(
+        'POST',
+        '/v1/work/run/start',
+        {
+          agent_id: requireAgentId(agent_id),
+          resource_type,
+          resource_key,
+          ...(label ? { label } : {}),
+          ...(start_at ? { start_at } : {}),
+          ...(duration_minutes ? { duration_minutes } : {}),
+          ...(reason ? { reason } : {}),
+          client_name: 'availsync-mcp',
+        },
+        idempotencyHeaders(idempotency_key),
+      );
+      await reportUsage('mcp_claim_work_slot', usage);
+      return jsonContent(result);
+    },
+  );
+
+  server.registerTool(
+    'extend_work_slot',
+    {
+      description:
+        'Extend an active guarded run claim while a coding agent is still working. Call periodically before expires_at.',
+      inputSchema: {
+        claim_id: z.string().uuid(),
+        duration_minutes: z.number().int().min(1).max(120).optional(),
+        usage: usageSchema,
+      },
+    },
+    async ({ claim_id, duration_minutes, usage }) => {
+      const result = await requestAvailsync('POST', '/v1/work/run/extend', {
+        claim_id,
+        ...(duration_minutes ? { duration_minutes } : {}),
+        client_name: 'availsync-mcp',
+      });
+      await reportUsage('mcp_extend_work_slot', usage);
+      return jsonContent(result);
+    },
+  );
+
+  server.registerTool(
+    'release_work_slot',
+    {
+      description: 'Finish a guarded repo/project run claim so another coding agent can work.',
+      inputSchema: {
+        claim_id: z.string().uuid(),
+        outcome: z.string().trim().min(1).max(100).optional(),
+        reason: z.string().trim().max(500).optional(),
+        usage: usageSchema,
+      },
+    },
+    async ({ claim_id, outcome, reason, usage }) => {
+      const result = await requestAvailsync('POST', '/v1/work/run/finish', {
+        claim_id,
+        outcome: outcome ?? 'finished',
+        ...(reason ? { reason } : {}),
+        client_name: 'availsync-mcp',
+      });
+      await reportUsage('mcp_release_work_slot', usage);
+      return jsonContent(result);
+    },
+  );
+
+  return server;
+}
+
+export async function main(): Promise<void> {
+  if (process.argv.includes('--help') || process.argv.includes('-h')) {
+    printHelp();
+    return;
+  }
+
+  const server = createServer();
+  const transport = new StdioServerTransport();
+  if (!process.env.AVAILSYNC_API_KEY) {
+    console.error('Availsync MCP warning: AVAILSYNC_API_KEY is not set. Tools will fail until it is configured.');
+  }
+  if (!configuredAgentId()) {
+    console.error('Availsync MCP warning: AVAILSYNC_AGENT_ID is not set. Pass agent_id in each tool call or configure the env var.');
+  }
+  void sendHeartbeat().catch(() => {});
+  const heartbeat = setInterval(() => {
+    void sendHeartbeat().catch(() => {});
+  }, 60_000);
+  heartbeat.unref?.();
+  await server.connect(transport);
+}
+
+const isDirectRun = process.argv[1] ? fileURLToPath(import.meta.url) === process.argv[1] : false;
+
+if (isDirectRun) {
+  main().catch((error) => {
+    console.error('Server error:', error);
+    process.exit(1);
+  });
+}

package/packages/mcp/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "lib": ["ES2022", "DOM"],
+    "types": ["node"],
+    "declaration": true,
+    "sourceMap": true,
+    "declarationMap": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "skipLibCheck": true
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["src/**/*.test.ts", "dist"]
+}

package/packages/mcp/tsconfig.test.json

@@ -0,0 +1,12 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "module": "CommonJS",
+    "moduleResolution": "Node",
+    "types": ["node", "jest"],
+    "declaration": false,
+    "declarationMap": false,
+    "sourceMap": false
+  },
+  "include": ["src/**/*.ts"]
+}

package/packages/node/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Availsync
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/packages/node/README.md

@@ -0,0 +1,120 @@
+# @availsync/node
+
+Node SDK for Availsync coding-agent work guardrails.
+
+Use it before Codex, Claude, Cursor, OpenClaw, cron jobs, deploy scripts, or other automations touch a protected repo or project.
+
+## Install
+
+```bash
+npm install @availsync/node@alpha
+```
+
+Use the explicit `@alpha` tag for pilots. The package is public, but the SDK API should be treated as prerelease until the first production pilots confirm the shape.
+
+## Environment
+
+```bash
+AVAILSYNC_API_KEY=avs_live_...
+AVAILSYNC_AGENT_ID=agent_uuid
+AVAILSYNC_API_URL=https://availsync.dev
+```
+
+## Guard a coding-agent run
+
+```ts
+import { createAvailsyncClient } from '@availsync/node';
+
+const availsync = createAvailsyncClient({
+  apiKey: process.env.AVAILSYNC_API_KEY!,
+  agentId: process.env.AVAILSYNC_AGENT_ID!,
+  baseUrl: process.env.AVAILSYNC_API_URL,
+  timeoutMs: 30_000,
+});
+
+const result = await availsync.work.withClaim(
+  'repo:owner/repo',
+  { reason: 'scheduled Codex run', durationMinutes: 45 },
+  async ({ claim, shadow }) => {
+    if (shadow.wouldHaveBlocked) {
+      console.warn('Observe-only: Availsync would have skipped this run.');
+    }
+
+    const extendTimer = claim
+      ? setInterval(() => claim.extend({ durationMinutes: 45 }).catch(console.error), 40 * 60_000)
+      : null;
+
+    try {
+      await doWork();
+    } finally {
+      if (extendTimer) clearInterval(extendTimer);
+    }
+  },
+);
+
+if (result.action === 'skip_run') {
+  console.log(result.reason);
+}
+```
+
+## API surface
+
+- `createAvailsyncClient({ apiKey, agentId, baseUrl?, timeoutMs? })`
+- `client.work.withClaim(resource, options, fn)`
+- `client.work.start({ resource, durationMinutes?, reason?, idempotencyKey?, metadata? })`
+- `client.work.extend(claimId, { durationMinutes? })`
+- `client.work.finish(claimId, { outcome?, reason?, metadata? })`
+
+## Manual flow
+
+```ts
+const started = await availsync.work.start({
+  resource: 'repo:owner/repo',
+  reason: 'deploy automation',
+  durationMinutes: 45,
+  idempotencyKey: `deploy-${process.env.GITHUB_RUN_ID}`,
+});
+
+if (started.action === 'skip_run') {
+  console.log(started.reason);
+  process.exit(0);
+}
+
+if (started.shadow_mode && started.would_have_blocked) {
+  console.warn('Observe-only: Availsync would have skipped this run.');
+}
+
+const extendTimer = started.claim
+  ? setInterval(() => availsync.work.extend(started.claim!.id, { durationMinutes: 45 }).catch(console.error), 40 * 60_000)
+  : null;
+
+try {
+  await doWork();
+} finally {
+  if (extendTimer) clearInterval(extendTimer);
+  if (started.claim) {
+    await availsync.work.finish(started.claim.id, { outcome: 'finished' });
+  }
+}
+```
+
+## Observe-only pilots
+
+Set an agent to Observe in the dashboard when you want Availsync to report what it would have blocked without stopping the automation. Observe mode returns `action: "proceed"` and `claim: null`; no lease is created, so `extend` and `finish` are no-ops you should skip.
+
+## Error handling
+
+The SDK throws `AvailsyncError` for auth, validation, plan-limit, network, and unexpected API errors. The error includes `code`, `status`, and safe `details` from the API response. It never logs or exposes API keys.
+
+## Resource scope
+
+- `repo:owner/repo` is the safe default. Only one active agent can work in the repo.
+- `project:homepage` allows parallel work, but only use it for independent work streams.
+- Availsync does not yet infer dependencies between different resources.
+
+## Local development
+
+```bash
+npm run build:sdk
+npm run test:sdk
+```

package/packages/node/jest.config.cjs

@@ -0,0 +1,8 @@
+module.exports = {
+  preset: 'ts-jest',
+  testEnvironment: 'node',
+  testMatch: ['<rootDir>/src/**/*.test.ts'],
+  transform: {
+    '^.+\\.ts$': ['ts-jest', { tsconfig: '<rootDir>/tsconfig.test.json' }],
+  },
+};

package/packages/node/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@availsync/node",
+  "version": "0.1.0-alpha.3",
+  "description": "Node SDK for Availsync coding-agent work guardrails.",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "homepage": "https://availsync.dev",
+  "keywords": [
+    "availsync",
+    "ai-agents",
+    "coding-agents",
+    "guardrails",
+    "mcp",
+    "automation",
+    "repo-locks"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "tag": "alpha"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepack": "npm run build",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "jest --config jest.config.cjs --runInBand"
+  },
+  "dependencies": {},
+  "devDependencies": {}
+}