@fabric-harness/azure 0.5.0 → 0.6.0

package/README.md

@@ -9,11 +9,42 @@ Current surface:
 - `createAzureKeyVaultSecretResolver()` — Key Vault secret resolver for scoped commands.
 - `FoundryAgentServiceClient` / `foundryAgentTool()` — invoke Azure AI Foundry Agent Service from Fabric agents.
 - `AzureArmClient` tools for Container Apps jobs, AKS Run Command, and ACI exec-session creation.
+- **`aksSandbox()`** (subpath: `@fabric-harness/azure/aks-sandbox`) — full `SandboxEnv` runtime backed by an AKS pod. Pulls cluster credentials via ARM `listClusterUserCredential` and delegates to `kubernetesSandbox` from `@fabric-harness/connectors/k8s`.
 
 ## Install
 
 ```sh
 npm install @fabric-harness/azure @fabric-harness/sdk
+
+# Optional: required only when using aksSandbox
+npm install @kubernetes/client-node
+```
+
+## AKS sandbox (full SandboxEnv)
+
+Run an entire agent inside an AKS pod — `exec`/`readFile`/`writeFile`/`mkdir`/`rm` all work over the pod.
+
+```ts
+import { init } from '@fabric-harness/sdk';
+import { createAzureArmClient } from '@fabric-harness/azure';
+import { aksSandbox } from '@fabric-harness/azure/aks-sandbox';
+
+const arm = createAzureArmClient({
+  subscriptionId: process.env.AZURE_SUBSCRIPTION_ID!,
+  token: process.env.AZURE_ACCESS_TOKEN!,
+});
+
+const sandbox = await aksSandbox({
+  arm,
+  resourceGroup: 'my-rg',
+  clusterName: 'my-aks',
+  // Either attach to an existing pod:
+  podName: 'agent-pod',
+  // Or create an ephemeral pod from an image (auto-deleted on cleanup):
+  // image: 'alpine:latest',
+});
+
+const fabric = await init({ sandbox });
 ```
 
 ## Foundry Agent Service as a tool
@@ -39,6 +70,10 @@ const arm = createAzureArmClient({ subscriptionId: process.env.AZURE_SUBSCRIPTIO
 const tools = [azureContainerAppsJobTool(arm), azureAksRunCommandTool(arm)];
 ```
 
+## Build targets
+
+`fh build --target aks` and `fh build --target aca` emit the deployment scaffolding for AKS (k8s manifests with health probes) and Azure Container Apps (azd project + Bicep with scale-to-zero) respectively. See [Azure deployment](https://harness.fabric.pro/docs/deployment/azure).
+
 Keep Azure credentials in environment variables, managed identity token providers, or secret stores. Do not put tokens in prompts or payloads.
 
 ## License

package/dist/aks-sandbox.d.ts

@@ -0,0 +1,35 @@
+import type { SandboxEnv } from '@fabric-harness/sdk';
+import type { AzureArmClient } from './index.js';
+/**
+ * AKS-flavored Kubernetes sandbox. Pulls cluster credentials from the AKS
+ * `listClusterUserCredentials` endpoint, builds a `@kubernetes/client-node`
+ * `KubeConfig`, and delegates to `kubernetesSandbox`.
+ *
+ * Requires both peer deps:
+ * ```sh
+ * npm install @kubernetes/client-node
+ * ```
+ *
+ * Pod lifecycle: by default this attaches to an existing pod. To have the
+ * sandbox create its own ephemeral pod from an image, supply `image` and the
+ * pod will be created on first use and deleted on `cleanup()`.
+ */
+export interface AksSandboxOptions {
+    arm: AzureArmClient;
+    resourceGroup: string;
+    clusterName: string;
+    /** Kubernetes namespace. Defaults to `default`. */
+    namespace?: string;
+    /** Existing pod name to attach to. Mutually exclusive with `image`. */
+    podName?: string;
+    /** Container image. If set, AKS sandbox creates an ephemeral pod and deletes it on cleanup. */
+    image?: string;
+    /** Container name inside the pod. */
+    container?: string;
+    /** AKS API version. */
+    apiVersion?: string;
+    /** Working directory inside the pod. Defaults to `/workspace`. */
+    cwd?: string;
+}
+export declare function aksSandbox(options: AksSandboxOptions): Promise<SandboxEnv>;
+//# sourceMappingURL=aks-sandbox.d.ts.map

package/dist/aks-sandbox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"aks-sandbox.d.ts","sourceRoot":"","sources":["../src/aks-sandbox.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAIjD;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,iBAAiB;IAChC,GAAG,EAAE,cAAc,CAAC;IACpB,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,mDAAmD;IACnD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,uEAAuE;IACvE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,+FAA+F;IAC/F,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,qCAAqC;IACrC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,uBAAuB;IACvB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,kEAAkE;IAClE,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,wBAAsB,UAAU,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,UAAU,CAAC,CAsDhF"}

package/dist/aks-sandbox.js

@@ -0,0 +1,64 @@
+import { createRequire } from 'node:module';
+import { kubernetesSandbox, createKubernetesPod } from '@fabric-harness/connectors/k8s';
+const requireFromHere = createRequire(import.meta.url);
+export async function aksSandbox(options) {
+    if (!options.podName && !options.image) {
+        throw new Error('aksSandbox: provide either `podName` (attach) or `image` (ephemeral pod).');
+    }
+    const namespace = options.namespace ?? 'default';
+    const apiVersion = options.apiVersion ?? '2024-02-01';
+    const credResponse = await options.arm.request('POST', options.arm.resourcePath(options.resourceGroup, `Microsoft.ContainerService/managedClusters/${encodeURIComponent(options.clusterName)}/listClusterUserCredential`), undefined, { 'api-version': apiVersion });
+    const encoded = credResponse.kubeconfigs?.[0]?.value;
+    if (!encoded)
+        throw new Error(`aksSandbox: no kubeconfig returned for ${options.resourceGroup}/${options.clusterName}`);
+    const kubeconfig = Buffer.from(encoded, 'base64').toString('utf8');
+    const { KubeConfig, CoreV1Api } = loadK8sModule();
+    const kc = new KubeConfig();
+    kc.loadFromString(kubeconfig);
+    let podName = options.podName;
+    let ownsPod = false;
+    if (!podName) {
+        podName = `fabric-harness-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
+        const core = kc.makeApiClient(CoreV1Api);
+        await core.createNamespacedPod(namespace, {
+            apiVersion: 'v1',
+            kind: 'Pod',
+            metadata: { name: podName, labels: { 'app.kubernetes.io/managed-by': 'fabric-harness' } },
+            spec: {
+                restartPolicy: 'Never',
+                containers: [{
+                        name: options.container ?? 'main',
+                        image: options.image,
+                        command: ['sh', '-c', 'mkdir -p /workspace && sleep infinity'],
+                        workingDir: options.cwd ?? '/workspace',
+                    }],
+            },
+        });
+        ownsPod = true;
+    }
+    const pod = createKubernetesPod({
+        kubeConfig: kc,
+        namespace,
+        podName,
+        ...(options.container ? { container: options.container } : {}),
+        ownsPod,
+    });
+    return kubernetesSandbox(pod, {
+        cwd: options.cwd ?? '/workspace',
+        cleanup: ownsPod,
+    });
+}
+let cachedK8sModule;
+function loadK8sModule() {
+    if (cachedK8sModule)
+        return cachedK8sModule;
+    try {
+        const mod = requireFromHere('@kubernetes/client-node');
+        cachedK8sModule = mod;
+        return mod;
+    }
+    catch {
+        throw new Error('aksSandbox requires the `@kubernetes/client-node` peer dependency. Install it with: npm install @kubernetes/client-node');
+    }
+}
+//# sourceMappingURL=aks-sandbox.js.map

package/dist/aks-sandbox.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"aks-sandbox.js","sourceRoot":"","sources":["../src/aks-sandbox.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fabric-harness/azure",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Azure Container Apps / Container Instances / AKS adapter for Fabric Harness.",
   "license": "Apache-2.0",
   "author": "Fabric",
@@ -32,15 +32,35 @@
   },
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./aks-sandbox": {
+      "types": "./dist/aks-sandbox.d.ts",
+      "import": "./dist/aks-sandbox.js"
+    }
+  },
   "files": [
     "dist",
     "README.md",
     "LICENSE"
   ],
   "dependencies": {
-    "@fabric-harness/sdk": "0.5.0"
+    "@fabric-harness/connectors": "0.6.0",
+    "@fabric-harness/sdk": "0.6.0"
+  },
+  "peerDependencies": {
+    "@kubernetes/client-node": "^0.21.0"
+  },
+  "peerDependenciesMeta": {
+    "@kubernetes/client-node": {
+      "optional": true
+    }
   },
   "devDependencies": {
+    "@kubernetes/client-node": "^0.21.0",
     "@types/node": "^22.15.3",
     "typescript": "^5.8.3",
     "vitest": "^4.1.5"